diff --git a/.github/dependabot.yml b/.github/dependabot.yml deleted file mode 100644 index ec459e5..0000000 --- a/.github/dependabot.yml +++ /dev/null @@ -1,34 +0,0 @@ -version: 2 -updates: - - package-ecosystem: "uv" - directory: "/backend" - schedule: - interval: "weekly" - groups: - backend-dependencies: - patterns: - - "*" - - - package-ecosystem: "npm" - directory: "/frontend" - schedule: - interval: "weekly" - groups: - frontend-dependencies: - patterns: - - "*" - - - package-ecosystem: "github-actions" - directory: "/" - schedule: - interval: "weekly" - - - package-ecosystem: "docker" - directory: "/backend" - schedule: - interval: "weekly" - - - package-ecosystem: "docker" - directory: "/frontend" - schedule: - interval: "weekly" diff --git a/.github/workflows/cd.yml b/.github/workflows/cd.yml index ca67357..cb770a2 100644 --- a/.github/workflows/cd.yml +++ b/.github/workflows/cd.yml @@ -19,6 +19,10 @@ env: RESOURCE_GROUP: trueup-mvp-rg REGISTRY: trueupmvpacr.azurecr.io IMAGE_TAG: ${{ github.event.workflow_run.head_sha }} + CONTAINER_ENV: trueup-mvp-env + KEY_VAULT_URI: https://trueup-mvp-kv.vault.azure.net/ + KEY_VAULT_ID: /subscriptions/5c16376b-0431-4786-895e-93e01db5f553/resourceGroups/trueup-mvp-rg/providers/Microsoft.KeyVault/vaults/trueup-mvp-kv + KEYVAULT_WRAP_KEY_NAME: trueup-wrap-key jobs: build-and-push: @@ -120,7 +124,7 @@ jobs: --name frontend \ --resource-group ${{ env.RESOURCE_GROUP }} \ --image ${{ env.REGISTRY }}/trueup-frontend:${{ env.IMAGE_TAG }} - - name: Verify health + - name: Verify backend + frontend health run: | FQDN=$(az containerapp show --name frontend --resource-group ${{ env.RESOURCE_GROUP }} --query properties.configuration.ingress.fqdn -o tsv) for i in $(seq 1 10); do @@ -129,3 +133,168 @@ jobs: sleep 5 done echo "::error::Deployed frontend never reported healthy" && exit 1 + + deploy-worker-and-mcp-server: + name: Deploy worker + mcp-server + needs: migrate + runs-on: ubuntu-latest + environment: production + steps: + - name: Azure login (OIDC) + uses: azure/login@v2 + with: + client-id: ${{ secrets.AZURE_CLIENT_ID }} + tenant-id: ${{ secrets.AZURE_TENANT_ID }} + subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }} + # Both worker (ADR 13's always-on job_outbox drain process) and mcp-server (S13/ADR 24's + # MCP agent surface) reuse the backend image with a different command -- the same "different + # process, same database" shape docker-compose.yml already establishes locally. Neither + # existed as a Container App before this workflow; both are created idempotently here (a + # first run creates, every run after just updates the image) rather than provisioned by + # hand outside the pipeline, so this workflow is the one place their config is defined. + - name: Create or update the worker Container App + run: | + if az containerapp show --name worker --resource-group ${{ env.RESOURCE_GROUP }} &>/dev/null; then + echo "worker exists -- updating image only" + az containerapp update \ + --name worker \ + --resource-group ${{ env.RESOURCE_GROUP }} \ + --image ${{ env.REGISTRY }}/trueup-backend:${{ env.IMAGE_TAG }} + exit 0 + fi + + echo "worker does not exist -- bootstrapping" + az containerapp create \ + --name worker \ + --resource-group ${{ env.RESOURCE_GROUP }} \ + --environment ${{ env.CONTAINER_ENV }} \ + --image ${{ env.REGISTRY }}/trueup-backend:${{ env.IMAGE_TAG }} \ + --command flask \ + --args "jobs" "outbox-worker" \ + --min-replicas 1 --max-replicas 1 \ + --system-assigned \ + --registry-server ${{ env.REGISTRY }} + + PRINCIPAL_ID=$(az containerapp show --name worker --resource-group ${{ env.RESOURCE_GROUP }} --query identity.principalId -o tsv) + az role assignment create --assignee "$PRINCIPAL_ID" --role "Key Vault Secrets User" --scope ${{ env.KEY_VAULT_ID }} + az role assignment create --assignee "$PRINCIPAL_ID" --role "Key Vault Crypto User" --scope ${{ env.KEY_VAULT_ID }} + + # RBAC assignments are not instantaneous -- the secret-set step below resolves each + # keyvaultref immediately, so a fixed wait here is the simplest correct fix (confirmed + # during the manual OIDC setup earlier this session: ~15s was sufficient in practice). + sleep 30 + + az containerapp secret set \ + --name worker \ + --resource-group ${{ env.RESOURCE_GROUP }} \ + --secrets \ + database-url=keyvaultref:${{ env.KEY_VAULT_URI }}secrets/database-url,identityref:system \ + database-url-worker=keyvaultref:${{ env.KEY_VAULT_URI }}secrets/database-url-worker,identityref:system \ + database-url-owner=keyvaultref:${{ env.KEY_VAULT_URI }}secrets/database-url-owner,identityref:system \ + database-url-chat=keyvaultref:${{ env.KEY_VAULT_URI }}secrets/database-url-chat,identityref:system \ + redis-url=keyvaultref:${{ env.KEY_VAULT_URI }}secrets/redis-url,identityref:system \ + secret-key=keyvaultref:${{ env.KEY_VAULT_URI }}secrets/secret-key,identityref:system \ + stripe-secret-key=keyvaultref:${{ env.KEY_VAULT_URI }}secrets/stripe-secret-key,identityref:system \ + alpaca-api-key-id=keyvaultref:${{ env.KEY_VAULT_URI }}secrets/alpaca-api-key-id,identityref:system \ + alpaca-api-secret-key=keyvaultref:${{ env.KEY_VAULT_URI }}secrets/alpaca-api-secret-key,identityref:system + + az containerapp update \ + --name worker \ + --resource-group ${{ env.RESOURCE_GROUP }} \ + --set-env-vars \ + FLASK_ENV=production \ + FLASK_APP=wsgi \ + DATABASE_URL=secretref:database-url \ + DATABASE_URL_WORKER=secretref:database-url-worker \ + DATABASE_URL_OWNER=secretref:database-url-owner \ + DATABASE_URL_CHAT=secretref:database-url-chat \ + REDIS_URL=secretref:redis-url \ + SECRET_KEY=secretref:secret-key \ + AZURE_KEY_VAULT_URL=${{ env.KEY_VAULT_URI }} \ + AZURE_KEYVAULT_WRAP_KEY_NAME=${{ env.KEYVAULT_WRAP_KEY_NAME }} \ + STRIPE_SECRET_KEY=secretref:stripe-secret-key \ + ALPACA_API_KEY_ID=secretref:alpaca-api-key-id \ + ALPACA_API_SECRET_KEY=secretref:alpaca-api-secret-key \ + ALPACA_BASE_URL=https://paper-api.alpaca.markets \ + FEE_RATE_PCT=0.0 + - name: Create or update the mcp-server Container App + run: | + if az containerapp show --name mcp-server --resource-group ${{ env.RESOURCE_GROUP }} &>/dev/null; then + echo "mcp-server exists -- updating image only" + az containerapp update \ + --name mcp-server \ + --resource-group ${{ env.RESOURCE_GROUP }} \ + --image ${{ env.REGISTRY }}/trueup-backend:${{ env.IMAGE_TAG }} + exit 0 + fi + + echo "mcp-server does not exist -- bootstrapping" + # External ingress: an MCP client connects from outside Azure (ADR 24 "Transport and + # deployment"). Auth is the app's own staff_api_token bearer check on every tool call + # (app/mcp/auth.py), not network-level restriction -- matching backend's own external + # ingress, which relies on its session/CSRF layer the same way. + az containerapp create \ + --name mcp-server \ + --resource-group ${{ env.RESOURCE_GROUP }} \ + --environment ${{ env.CONTAINER_ENV }} \ + --image ${{ env.REGISTRY }}/trueup-backend:${{ env.IMAGE_TAG }} \ + --command python \ + --args "app/mcp/entrypoint.py" \ + --min-replicas 1 --max-replicas 1 \ + --system-assigned \ + --ingress external \ + --target-port 8001 \ + --registry-server ${{ env.REGISTRY }} + + PRINCIPAL_ID=$(az containerapp show --name mcp-server --resource-group ${{ env.RESOURCE_GROUP }} --query identity.principalId -o tsv) + az role assignment create --assignee "$PRINCIPAL_ID" --role "Key Vault Secrets User" --scope ${{ env.KEY_VAULT_ID }} + az role assignment create --assignee "$PRINCIPAL_ID" --role "Key Vault Crypto User" --scope ${{ env.KEY_VAULT_ID }} + + sleep 30 + + az containerapp secret set \ + --name mcp-server \ + --resource-group ${{ env.RESOURCE_GROUP }} \ + --secrets \ + database-url=keyvaultref:${{ env.KEY_VAULT_URI }}secrets/database-url,identityref:system \ + database-url-worker=keyvaultref:${{ env.KEY_VAULT_URI }}secrets/database-url-worker,identityref:system \ + database-url-owner=keyvaultref:${{ env.KEY_VAULT_URI }}secrets/database-url-owner,identityref:system \ + database-url-chat=keyvaultref:${{ env.KEY_VAULT_URI }}secrets/database-url-chat,identityref:system \ + redis-url=keyvaultref:${{ env.KEY_VAULT_URI }}secrets/redis-url,identityref:system \ + secret-key=keyvaultref:${{ env.KEY_VAULT_URI }}secrets/secret-key,identityref:system + + az containerapp update \ + --name mcp-server \ + --resource-group ${{ env.RESOURCE_GROUP }} \ + --set-env-vars \ + FLASK_ENV=production \ + DATABASE_URL=secretref:database-url \ + DATABASE_URL_WORKER=secretref:database-url-worker \ + DATABASE_URL_OWNER=secretref:database-url-owner \ + DATABASE_URL_CHAT=secretref:database-url-chat \ + REDIS_URL=secretref:redis-url \ + SECRET_KEY=secretref:secret-key \ + AZURE_KEY_VAULT_URL=${{ env.KEY_VAULT_URI }} \ + AZURE_KEYVAULT_WRAP_KEY_NAME=${{ env.KEYVAULT_WRAP_KEY_NAME }} \ + FEE_RATE_PCT=0.0 \ + MCP_SERVER_HOST=0.0.0.0 \ + MCP_SERVER_PORT=8001 + - name: Verify worker is running (no HTTP endpoint of its own) + run: | + for i in $(seq 1 10); do + STATE=$(az containerapp revision list --name worker --resource-group ${{ env.RESOURCE_GROUP }} --query "[0].properties.runningState" -o tsv) + [ "$STATE" = "Running" ] && echo "worker running" && exit 0 + sleep 5 + done + echo "::error::worker never reached Running state ($STATE)" && exit 1 + - name: Verify mcp-server health + run: | + FQDN=$(az containerapp show --name mcp-server --resource-group ${{ env.RESOURCE_GROUP }} --query properties.configuration.ingress.fqdn -o tsv) + for i in $(seq 1 10); do + # No /health route on the MCP transport itself -- a bare TCP/HTTP reachability check + # against the streamable-HTTP path is what proves the process is actually listening. + CODE=$(curl -s -o /dev/null -w "%{http_code}" "https://$FQDN/mcp" || echo "000") + [ "$CODE" != "000" ] && echo "mcp-server reachable (HTTP $CODE)" && exit 0 + sleep 5 + done + echo "::error::mcp-server never became reachable" && exit 1 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d73f736..1163b6a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,9 +1,11 @@ name: CI -# Root CLAUDE.md ("CI/CD (GitHub Actions)"): lint, unit + integration tests, API tests, UI -# component tests, coverage thresholds; dependency and secret scanning, SAST, Docker build + -# image vulnerability scan, Alembic migration check. Runs on every PR marked ready for review and -# on main -- draft PRs stay cheap to iterate on locally. +# Scope, deliberately narrowed (2026-09-06): tests + coverage floor, Alembic migration check, +# SAST (Bandit + Semgrep), secret scanning, and Docker build + image vulnerability scan -- each +# job here catches a real, distinct class of defect a merge could otherwise ship. Lint/typecheck/ +# import-layering/dependency-audit stay local-only (`make lint`/`typecheck`/`imports`/`audit`, +# `npm run lint`) rather than CI gates. Runs on every PR marked ready for review and on main -- +# draft PRs stay cheap to iterate on locally. on: pull_request: types: [opened, synchronize, reopened, ready_for_review] @@ -18,29 +20,6 @@ env: UV_VERSION: "0.5.11" jobs: - backend-quality: - name: Backend / lint, types, imports - if: github.event.pull_request.draft != true - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: astral-sh/setup-uv@v3 - with: - version: ${{ env.UV_VERSION }} - - run: uv sync --project backend --all-extras - # `working-directory: backend` on every step below, not just the last one: mypy and ruff - # both auto-discover `backend/pyproject.toml` (the `[tool.mypy]` overrides -- the pydantic - # plugin, the flask_*/alpaca/plaid ignore_missing_imports list) only when invoked from that - # directory. Running from the repo root silently drops all of it, which is a materially - # different, much noisier check (confirmed the hard way: passed locally under `cwd=backend`, - # failed in CI with 34 spurious errors before this fix). - - run: uv run --project backend ruff check app tests - working-directory: backend - - run: uv run --project backend mypy --strict app - working-directory: backend - - run: uv run --project backend lint-imports - working-directory: backend - backend-tests: name: Backend / tests + coverage floor if: github.event.pull_request.draft != true @@ -93,18 +72,6 @@ jobs: name: backend-coverage path: backend/coverage.xml - backend-dependency-audit: - name: Backend / dependency scan - if: github.event.pull_request.draft != true - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: astral-sh/setup-uv@v3 - with: - version: ${{ env.UV_VERSION }} - - run: uv sync --project backend --all-extras - - run: uv run --project backend pip-audit - backend-sast: name: Backend / SAST (Bandit + Semgrep) if: github.event.pull_request.draft != true @@ -182,47 +149,6 @@ jobs: rm -f "$GENERATED" working-directory: backend - frontend-quality: - name: Frontend / lint, test, build - if: github.event.pull_request.draft != true - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 - with: - node-version: "20" - cache: "npm" - cache-dependency-path: frontend/package-lock.json - - run: npm ci - working-directory: frontend - - run: npm run lint - working-directory: frontend - # `npm test` only exists once Phase 7 installs Vitest -- until then this step is a no-op - # guarded by the script's own presence so earlier phases' CI runs stay green honestly - # rather than via a fabricated always-pass step. - - name: Run component tests (if configured) - run: | - if npm run | grep -q " test$"; then npm run test -- --run; else echo "no test script yet"; fi - working-directory: frontend - - run: npm run build - working-directory: frontend - - frontend-dependency-audit: - name: Frontend / dependency scan - if: github.event.pull_request.draft != true - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 - with: - node-version: "20" - cache: "npm" - cache-dependency-path: frontend/package-lock.json - - run: npm ci - working-directory: frontend - - run: npm audit --audit-level=high - working-directory: frontend - secret-scan: name: Secret scanning (Gitleaks) if: github.event.pull_request.draft != true @@ -257,6 +183,10 @@ jobs: push: false load: true tags: trueup-${{ matrix.image }}:ci + # Genuinely finds real, fixable vulnerabilities, not a rubber-stamp step -- confirmed the + # hard way: this exact scan caught CVE-2026-31789 (CRITICAL) in nginx:1.27-alpine's OpenSSL + # packages, fixed by bumping the base image and adding `apk upgrade` at build time + # (frontend/Dockerfile). `severity: CRITICAL,HIGH` + `exit-code: 1` actually fails the job. - name: Scan image for vulnerabilities uses: aquasecurity/trivy-action@v0.36.0 with: diff --git a/backend/.importlinter b/backend/.importlinter index 3deb147..3ec00f9 100644 --- a/backend/.importlinter +++ b/backend/.importlinter @@ -7,10 +7,10 @@ root_package = app include_external_packages = False [importlinter:contract:layers] -name = Layered architecture: controllers/jobs -> services -> models -> core +name = Layered architecture: controllers/jobs/mcp -> services -> models -> core type = layers layers = - app.controllers : app.jobs + app.controllers : app.jobs : app.mcp app.services app.models app.core diff --git a/backend/alembic/versions/20260905_0944-fc5c875054d0_add_ops_spine.py b/backend/alembic/versions/20260905_0944-fc5c875054d0_add_ops_spine.py index 806722d..dfcb9dc 100644 --- a/backend/alembic/versions/20260905_0944-fc5c875054d0_add_ops_spine.py +++ b/backend/alembic/versions/20260905_0944-fc5c875054d0_add_ops_spine.py @@ -78,12 +78,7 @@ def upgrade() -> None: sa.PrimaryKeyConstraint('id', name=op.f('pk_job_run')) ) op.create_index('uq_job_run_daily_name_market_date', 'job_run', ['job_name', 'market_date'], unique=True, postgresql_where=sa.text("cadence = 'daily'")) - # Postgres's built-in date_trunc() is STABLE, not IMMUTABLE, so it cannot appear directly in an - # index expression ("functions in index expression must be marked IMMUTABLE"). market_date is a - # plain DATE (no timezone dependency), so truncating it to a month boundary is a pure function of - # its input -- genuinely immutable in fact, just not declared that way by Postgres's own catalog. - # A tiny SQL wrapper marked IMMUTABLE is the standard fix (S0 SS9's own index expression hits this - # unstated Postgres constraint verbatim). + # date_trunc() is STABLE not IMMUTABLE in Postgres; wrap it so it can be used in an index expression. op.execute(""" CREATE OR REPLACE FUNCTION job_run_month_start(d date) RETURNS date AS $$ SELECT date_trunc('month', d)::date @@ -109,8 +104,7 @@ def downgrade() -> None: op.drop_table('idempotency_key') op.drop_index('ix_admin_audit_log_customer_recorded', table_name='admin_audit_log') op.drop_table('admin_audit_log') - # drop_table() does not drop the Postgres ENUM types sa.Enum() created alongside these tables -- - # same pattern the identity migration already applies to its own three enums. + # drop_table() does not drop the Postgres ENUM types created alongside these tables. sa.Enum(name='job_run_status').drop(op.get_bind(), checkfirst=True) sa.Enum(name='job_cadence').drop(op.get_bind(), checkfirst=True) sa.Enum(name='job_outbox_status').drop(op.get_bind(), checkfirst=True) diff --git a/backend/alembic/versions/20260905_1148-a9f60402b7a1_add_s1_ledger.py b/backend/alembic/versions/20260905_1148-a9f60402b7a1_add_s1_ledger.py index 8ec4465..bf496ea 100644 --- a/backend/alembic/versions/20260905_1148-a9f60402b7a1_add_s1_ledger.py +++ b/backend/alembic/versions/20260905_1148-a9f60402b7a1_add_s1_ledger.py @@ -83,10 +83,7 @@ def upgrade() -> None: ) # ### end Alembic commands ### - # --- RLS: role-aware tenant isolation on every table carrying a (denormalized or native) - # customer_id (S0 §7.3, ADR 17). journal_entry and settlement_obligation carry no customer_id - # of their own in S1's schema -- see their model docstrings -- so they get no RLS policy here, - # matching inbound_event/job_outbox/job_run's precedent for tables with no tenant identity. + # RLS tenant isolation on every table carrying customer_id (S0 §7.3, ADR 17). op.execute(""" ALTER TABLE account ENABLE ROW LEVEL SECURITY; CREATE POLICY tenant_isolation ON account @@ -110,7 +107,7 @@ def upgrade() -> None: ); """) - # --- posting_before_insert: customer_id denormalization + dimension validation (S1 §3.3) --- + # posting_before_insert: denormalize customer_id and validate dimension (S1 §3.3). op.execute(""" CREATE OR REPLACE FUNCTION posting_denormalize_and_validate() RETURNS trigger AS $$ DECLARE @@ -135,7 +132,7 @@ def upgrade() -> None: FOR EACH ROW EXECUTE FUNCTION posting_denormalize_and_validate(); """) - # --- ledger_balance: cross-row zero-sum invariant, deferred to COMMIT (S1 §6, ADR 17) --- + # ledger_balance: cross-row zero-sum invariant, deferred to COMMIT (S1 §6, ADR 17). op.execute(""" CREATE OR REPLACE FUNCTION check_journal_entry_balance() RETURNS trigger AS $$ DECLARE @@ -158,7 +155,7 @@ def upgrade() -> None: EXECUTE FUNCTION check_journal_entry_balance(); """) - # --- settlement_obligation: status transitions exactly once, pending -> terminal (S1 §6) --- + # settlement_obligation: status transitions exactly once, pending -> terminal (S1 §6). op.execute(""" CREATE OR REPLACE FUNCTION settlement_obligation_single_transition() RETURNS trigger AS $$ BEGIN @@ -175,13 +172,7 @@ def upgrade() -> None: FOR EACH ROW EXECUTE FUNCTION settlement_obligation_single_transition(); """) - # --- append-only enforcement: no UPDATE/DELETE grant for journal_entry/posting, for either - # runtime credential -- a hard DB-level guarantee, not application discipline (S1 §6). The - # web app (trueup_app) and jobs/worker (trueup_worker) both only ever INSERT into the ledger; - # a correction is always a new row (ADR 1). trueup_owner (migrations) is unaffected -- REVOKE - # here only removes what docker/postgres/init.sql's ALTER DEFAULT PRIVILEGES granted to the - # two runtime roles. settlement_obligation keeps UPDATE (its one-time status transition, S1 - # §6) but loses DELETE -- it is a regulatory record of what was expected to settle and when. + # Append-only enforcement: revoke UPDATE/DELETE on journal_entry/posting for runtime roles (S1 §6, ADR 1). op.execute(""" REVOKE UPDATE, DELETE ON journal_entry FROM trueup_app, trueup_worker; REVOKE UPDATE, DELETE ON posting FROM trueup_app, trueup_worker; diff --git a/backend/alembic/versions/20260905_1220-f6a4ae1f1ee7_add_customer_receivable_account_role.py b/backend/alembic/versions/20260905_1220-f6a4ae1f1ee7_add_customer_receivable_account_role.py index ede1c38..57154fa 100644 --- a/backend/alembic/versions/20260905_1220-f6a4ae1f1ee7_add_customer_receivable_account_role.py +++ b/backend/alembic/versions/20260905_1220-f6a4ae1f1ee7_add_customer_receivable_account_role.py @@ -4,9 +4,7 @@ Revises: a9f60402b7a1 Create Date: 2026-09-05 12:20:13.375239 -S1 §3.1's `role` enum is explicitly extensible; this is S2's first extension (FR-6, S2 §5.2 step -4): a bounced deposit whose cash was already invested leaves a debt the customer owes, tracked as -a `customer_receivable` account (dimension `money`, same as every other money-role account). +Add customer_receivable account role for bounced-deposit debt (FR-6, S2 §5.2 step 4). """ from typing import Sequence, Union @@ -33,9 +31,7 @@ def upgrade() -> None: """Upgrade schema.""" - # ALTER TYPE ... ADD VALUE cannot be used in the same transaction that also references the new - # value (Postgres restriction) -- autocommit_block() runs it in its own committed transaction so - # the CHECK constraint below, which does reference it, is safe. + # ALTER TYPE ... ADD VALUE can't share a transaction with code that references the new value. with op.get_context().autocommit_block(): op.execute("ALTER TYPE account_role ADD VALUE IF NOT EXISTS 'customer_receivable';") @@ -45,18 +41,10 @@ def upgrade() -> None: def downgrade() -> None: """Downgrade schema.""" - # The CHECK constraint must be dropped *before* the type rebuild below, and only recreated - # *after* it: Postgres binds a CHECK constraint's literals to the column's enum type by OID at - # creation time, so recreating it against the old (7-value) type first and only then rebuilding - # the column's type underneath it raises "operator does not exist: account_role = - # account_role_old" -- the constraint's own compiled literals still point at the type being - # renamed away. + # Drop the CHECK constraint before rebuilding the enum type it binds to by OID. op.drop_constraint(op.f("ck_account_role_dimension"), "account", type_="check") - # Postgres has no ALTER TYPE ... DROP VALUE -- rebuild the enum type without it. Only safe when - # no row currently uses the value being removed (true for a clean downgrade with no - # customer_receivable accounts; S2's own data would need migrating off this role first in a - # real rollback, same caveat any enum-value removal carries). + # Postgres has no ALTER TYPE ... DROP VALUE -- rebuild the enum without it. op.execute("ALTER TYPE account_role RENAME TO account_role_old;") op.execute( "CREATE TYPE account_role AS ENUM " diff --git a/backend/alembic/versions/20260905_1230-263eb7564b1d_add_s4_valuation_and_market_data.py b/backend/alembic/versions/20260905_1230-263eb7564b1d_add_s4_valuation_and_market_data.py index a30e46c..d927f56 100644 --- a/backend/alembic/versions/20260905_1230-263eb7564b1d_add_s4_valuation_and_market_data.py +++ b/backend/alembic/versions/20260905_1230-263eb7564b1d_add_s4_valuation_and_market_data.py @@ -20,9 +20,7 @@ branch_labels: Union[str, Sequence[str], None] = None depends_on: Union[str, Sequence[str], None] = None -# `market_data_source` is shared by daily_close and market_calendar_cache (S4 §3.1/§3.4) -- -# created once explicitly, then referenced with create_type=False on each column so the second -# CREATE TABLE does not try to create the same Postgres enum type twice. +# Shared enum type across daily_close and market_calendar_cache (S4 §3.1/§3.4); create_type=False downstream. _market_data_source = postgresql.ENUM('live', 'simulated', name='market_data_source') @@ -86,9 +84,7 @@ def upgrade() -> None: sa.UniqueConstraint('customer_id', 'sub_period_start', 'sub_period_end', 'recorded_at', name='uq_sub_period_return_customer_period_recorded') ) - # --- RLS: role-aware tenant isolation on the one S4 table carrying a customer_id (S0 §7.3, - # ADR 17) -- security/daily_close/market_calendar_cache/valuation_run are whole-book/whole- - # market tables with no customer identity, matching inbound_event/job_run's precedent. + # RLS tenant isolation on the one S4 table carrying a customer_id (S0 §7.3, ADR 17). op.execute(""" ALTER TABLE sub_period_return ENABLE ROW LEVEL SECURITY; CREATE POLICY tenant_isolation ON sub_period_return @@ -98,11 +94,7 @@ def upgrade() -> None: ); """) - # --- append-only enforcement: daily_close/sub_period_return are bitemporal, correction-as- - # new-row tables (S4 §3.1/§3.5) -- no UPDATE/DELETE grant for either runtime credential, the - # same hard DB-level guarantee S1 §6 gives journal_entry/posting. market_calendar_cache and - # valuation_run stay mutable (upserted in place, S4 §3.2/§3.4), so they keep the default - # privileges docker/postgres/init.sql already grants. + # Append-only enforcement: daily_close/sub_period_return are correction-as-new-row (S4 §3.1/§3.5). op.execute(""" REVOKE UPDATE, DELETE ON daily_close FROM trueup_app, trueup_worker; REVOKE UPDATE, DELETE ON sub_period_return FROM trueup_app, trueup_worker; diff --git a/backend/alembic/versions/20260905_1240-5443b4a0f421_add_s3_orders_and_custody.py b/backend/alembic/versions/20260905_1240-5443b4a0f421_add_s3_orders_and_custody.py index 2a769b7..e59f11c 100644 --- a/backend/alembic/versions/20260905_1240-5443b4a0f421_add_s3_orders_and_custody.py +++ b/backend/alembic/versions/20260905_1240-5443b4a0f421_add_s3_orders_and_custody.py @@ -65,10 +65,7 @@ def upgrade() -> None: sa.UniqueConstraint('order_id', name=op.f('uq_approval_hold_order_id')) ) - # --- RLS: role-aware tenant isolation on `order`/`approval_hold` (S0 §7.3, ADR 17). - # `order_event` carries no customer_id of its own (S3 §3.2) -- no RLS policy here, matching - # journal_entry/settlement_obligation's precedent (S1): per-customer reads go through `order`, - # which is ownership-checked at the controller before any `order_event` query. + # RLS tenant isolation on `order`/`approval_hold` (S0 §7.3, ADR 17). op.execute(""" ALTER TABLE "order" ENABLE ROW LEVEL SECURITY; CREATE POLICY tenant_isolation ON "order" @@ -85,9 +82,7 @@ def upgrade() -> None: ); """) - # --- append-only enforcement: no UPDATE/DELETE grant for order_event, for either runtime - # credential (ADR 7, matching journal_entry/posting's precedent, S1 §6). `order` and - # `approval_hold` are plain mutable projections/rows and keep their default grants. + # Append-only enforcement: no UPDATE/DELETE grant for order_event (ADR 7). op.execute(""" REVOKE UPDATE, DELETE ON order_event FROM trueup_app, trueup_worker; """) diff --git a/backend/alembic/versions/20260905_1300-e07a426f914f_add_s5_tax_lot_account_roles.py b/backend/alembic/versions/20260905_1300-e07a426f914f_add_s5_tax_lot_account_roles.py index 97c9adf..a151e40 100644 --- a/backend/alembic/versions/20260905_1300-e07a426f914f_add_s5_tax_lot_account_roles.py +++ b/backend/alembic/versions/20260905_1300-e07a426f914f_add_s5_tax_lot_account_roles.py @@ -4,9 +4,7 @@ Revises: 5443b4a0f421 Create Date: 2026-09-05 13:00:00.000000 -S1 §3.1's `role` enum and §3.2's `entry_type` enum are both explicitly extensible; this is S5's -extension (FR-21/FR-23, ADR 11): `dividend_receivable`/`realized_gain_loss` (dimension `money`, -same as every other money-role account) plus the `wash_sale_adjustment` journal entry type. +Add dividend_receivable/realized_gain_loss account roles and wash_sale_adjustment entry type (FR-21/FR-23, ADR 11). """ from typing import Sequence, Union @@ -38,9 +36,7 @@ def upgrade() -> None: """Upgrade schema.""" - # ALTER TYPE ... ADD VALUE cannot be used in the same transaction that also references the new - # value (Postgres restriction) -- autocommit_block() runs each in its own committed transaction - # so the CHECK constraint below, which does reference the new account_role values, is safe. + # ALTER TYPE ... ADD VALUE can't share a transaction with code that references the new value. with op.get_context().autocommit_block(): op.execute("ALTER TYPE account_role ADD VALUE IF NOT EXISTS 'dividend_receivable';") op.execute("ALTER TYPE account_role ADD VALUE IF NOT EXISTS 'realized_gain_loss';") @@ -55,14 +51,10 @@ def upgrade() -> None: def downgrade() -> None: """Downgrade schema.""" - # The CHECK constraint must be dropped *before* the type rebuild below, and only recreated - # *after* it -- same ordering reason as f6a4ae1f1ee7's downgrade (Postgres binds a CHECK - # constraint's compiled literals to the column's enum type by OID at creation time). + # Drop the CHECK constraint before rebuilding the enum types it binds to by OID. op.drop_constraint(op.f("ck_account_role_dimension"), "account", type_="check") - # Postgres has no ALTER TYPE ... DROP VALUE -- rebuild both enum types without the added - # values. Only safe when no row currently uses them (true for a clean downgrade with no S5 - # data yet), same caveat any enum-value removal carries. + # Postgres has no ALTER TYPE ... DROP VALUE -- rebuild both enums without the added values. op.execute("ALTER TYPE account_role RENAME TO account_role_old;") op.execute( "CREATE TYPE account_role AS ENUM " diff --git a/backend/alembic/versions/20260905_1450-96d30b1b6cce_add_s5_tax_lot_lot_consumption_wash_.py b/backend/alembic/versions/20260905_1450-96d30b1b6cce_add_s5_tax_lot_lot_consumption_wash_.py index 96bd5af..d6fbd3a 100644 --- a/backend/alembic/versions/20260905_1450-96d30b1b6cce_add_s5_tax_lot_lot_consumption_wash_.py +++ b/backend/alembic/versions/20260905_1450-96d30b1b6cce_add_s5_tax_lot_lot_consumption_wash_.py @@ -65,9 +65,7 @@ def upgrade() -> None: sa.UniqueConstraint('original_lot_consumption_id', name='uq_wash_sale_original_consumption') ) - # --- RLS: role-aware tenant isolation on `tax_lot` (S0 §7.3, ADR 17) -- `lot_consumption`/ - # `wash_sale_adjustment` carry no customer_id of their own (S5 §3.2/§3.3), matching - # journal_entry/order_event's precedent: per-customer reads join through `tax_lot`. + # RLS tenant isolation on `tax_lot` (S0 §7.3, ADR 17). op.execute(""" ALTER TABLE tax_lot ENABLE ROW LEVEL SECURITY; CREATE POLICY tenant_isolation ON tax_lot diff --git a/backend/alembic/versions/20260905_1621-776c140e220a_add_s7_reconciliation_and_custodian_.py b/backend/alembic/versions/20260905_1621-776c140e220a_add_s7_reconciliation_and_custodian_.py index 012fd51..25997aa 100644 --- a/backend/alembic/versions/20260905_1621-776c140e220a_add_s7_reconciliation_and_custodian_.py +++ b/backend/alembic/versions/20260905_1621-776c140e220a_add_s7_reconciliation_and_custodian_.py @@ -46,13 +46,11 @@ def upgrade() -> None: sa.PrimaryKeyConstraint('id', name=op.f('pk_reconciliation_break')) ) - # --- append-only enforcement (S7 §3/§5.2): custodian_file_row is a preserved point-in-time - # import fact (no UPDATE/DELETE at all); reconciliation_break keeps UPDATE for the one - # controlled open -> resolved transition the trigger below polices, but never DELETE. + # Append-only enforcement (S7 §3/§5.2). op.execute("REVOKE UPDATE, DELETE ON custodian_file_row FROM trueup_app, trueup_worker;") op.execute("REVOKE DELETE ON reconciliation_break FROM trueup_app, trueup_worker;") - # --- single-transition + immutable-identifying-fields trigger (S7 §5.2, FR-44) ------------- + # Single-transition + immutable-identifying-fields trigger (S7 §5.2, FR-44). op.execute(""" CREATE OR REPLACE FUNCTION reconciliation_break_single_transition() RETURNS trigger AS $$ BEGIN @@ -80,9 +78,7 @@ def upgrade() -> None: FOR EACH ROW EXECUTE FUNCTION reconciliation_break_single_transition(); """) - # --- RLS: role-aware tenant isolation (S0 §7.3, ADR 17) -- a break with no customer - # attribution (customer_id IS NULL) is visible only to adviser/admin, matching account's own - # house-account exclusion. + # RLS tenant isolation (S0 §7.3, ADR 17). op.execute(""" ALTER TABLE reconciliation_break ENABLE ROW LEVEL SECURITY; CREATE POLICY tenant_isolation ON reconciliation_break diff --git a/backend/alembic/versions/20260905_1644-42545d3cedde_make_admin_audit_log_target_customer_id_.py b/backend/alembic/versions/20260905_1644-42545d3cedde_make_admin_audit_log_target_customer_id_.py index 14f7cb6..5ba63c2 100644 --- a/backend/alembic/versions/20260905_1644-42545d3cedde_make_admin_audit_log_target_customer_id_.py +++ b/backend/alembic/versions/20260905_1644-42545d3cedde_make_admin_audit_log_target_customer_id_.py @@ -20,10 +20,7 @@ def upgrade() -> None: """Upgrade schema.""" - # Not every audited action has a single-customer target -- e.g. resolving a - # reconciliation_break with no customer attribution (S7 §5.2). The audit trail - # (actor/action/payload-hash) still applies; there is simply no customer to index that one - # row under. + # Not every audited action has a single-customer target (S7 §5.2). op.alter_column('admin_audit_log', 'target_customer_id', nullable=True) diff --git a/backend/alembic/versions/20260905_1700-9b1c7a4f3d02_add_s11_chat_assistant.py b/backend/alembic/versions/20260905_1700-9b1c7a4f3d02_add_s11_chat_assistant.py index 25ce43f..6e85c30 100644 --- a/backend/alembic/versions/20260905_1700-9b1c7a4f3d02_add_s11_chat_assistant.py +++ b/backend/alembic/versions/20260905_1700-9b1c7a4f3d02_add_s11_chat_assistant.py @@ -69,8 +69,7 @@ def upgrade() -> None: sa.PrimaryKeyConstraint('id', name=op.f('pk_chat_tool_call')), ) - # --- RLS: role-aware tenant isolation (S0 §7.3, ADR 17), same shape as every other table - # carrying a (native or denormalized) customer_id. ------------------------------------------- + # RLS tenant isolation (S0 §7.3, ADR 17). op.execute(""" ALTER TABLE chat_session ENABLE ROW LEVEL SECURITY; CREATE POLICY tenant_isolation ON chat_session @@ -94,8 +93,7 @@ def upgrade() -> None: ); """) - # --- customer_id denormalization triggers (chat_message from chat_session, chat_tool_call - # from chat_message) -- app/models/chat/chat_message.py and chat_tool_call.py's own comments. -- + # customer_id denormalization triggers (chat_message from chat_session, chat_tool_call from chat_message). op.execute(""" CREATE OR REPLACE FUNCTION chat_message_denormalize_customer_id() RETURNS trigger AS $$ BEGIN @@ -120,8 +118,7 @@ def upgrade() -> None: FOR EACH ROW EXECUTE FUNCTION chat_tool_call_denormalize_customer_id(); """) - # --- chat_message_single_finalize: content moves past '' at most once (app/models/chat/ - # chat_message.py's own comment; mirrors settlement_obligation_single_transition, S1 §6). ----- + # chat_message_single_finalize: content moves past '' at most once (mirrors S1 §6). op.execute(""" CREATE OR REPLACE FUNCTION chat_message_single_finalize() RETURNS trigger AS $$ BEGIN @@ -141,18 +138,13 @@ def upgrade() -> None: FOR EACH ROW EXECUTE FUNCTION chat_message_single_finalize(); """) - # --- append-only enforcement: chat_message never DELETEs (UPDATE is allowed exactly once, via - # the trigger above); chat_tool_call is a pure audit trail, no UPDATE/DELETE at all (FR-53). --- + # Append-only enforcement (FR-53). op.execute(""" REVOKE DELETE ON chat_message FROM trueup_app, trueup_worker; REVOKE UPDATE, DELETE ON chat_tool_call FROM trueup_app, trueup_worker; """) - # --- ADR 19 safety perimeter: the 8 curated read-model views, owner-executed with an inline - # tenant predicate (see app/models/chat/curated_views.py's module docstring for why this is - # not `security_invoker = true` as ADR 19's literal sketch shows), plus the one-shot GRANT to - # `chat_readonly` (`trueup_chat_readonly`, provisioned in docker/postgres/init.sql, matching - # `trueup_app`/`trueup_worker`'s own provisioning-outside-migrations precedent). --------------- + # Curated read-model views + GRANT to chat_readonly (ADR 19). op.execute(CREATE_CURATED_VIEWS_SQL) op.execute(GRANT_CURATED_VIEWS_SQL) diff --git a/backend/alembic/versions/20260905_1903-80985c1b5653_add_s9_rebalancing.py b/backend/alembic/versions/20260905_1903-80985c1b5653_add_s9_rebalancing.py index 128b9b3..ea4b416 100644 --- a/backend/alembic/versions/20260905_1903-80985c1b5653_add_s9_rebalancing.py +++ b/backend/alembic/versions/20260905_1903-80985c1b5653_add_s9_rebalancing.py @@ -17,12 +17,7 @@ branch_labels: Union[str, Sequence[str], None] = None depends_on: Union[str, Sequence[str], None] = None -# NOTE: `alembic revision --autogenerate` also proposed `bank_link`, `kyc_session`, and a -# `chat_message.content` server_default change here -- none of them belong to S9. Those three are -# a pre-existing drift between the live models and what an earlier migration actually created -# (flagged to `main`, not fixed here: touching another sub-project's migration file while its own -# wave may still be in flight is out of this change's scope). This revision includes only the -# three tables S9 §3 actually owns. +# Autogenerate also proposed unrelated drift (bank_link, kyc_session, chat_message default); excluded here. def upgrade() -> None: @@ -52,9 +47,7 @@ def upgrade() -> None: sa.PrimaryKeyConstraint('customer_id', name=op.f('pk_customer_model_assignment')) ) - # --- RLS: role-aware tenant isolation on customer_model_assignment (S0 §7.3, ADR 17). - # model_portfolio/target_weight carry no customer_id -- every customer can reference the same - # model, matching security's own precedent (S4 §3.3) -- so neither gets a policy here. + # RLS tenant isolation on customer_model_assignment (S0 §7.3, ADR 17). op.execute(""" ALTER TABLE customer_model_assignment ENABLE ROW LEVEL SECURITY; CREATE POLICY tenant_isolation ON customer_model_assignment @@ -64,7 +57,7 @@ def upgrade() -> None: ); """) - # --- target_weight_sum: cross-row sum-to-one invariant, deferred to COMMIT (S9 §3.2) --- + # target_weight_sum: cross-row sum-to-one invariant, deferred to COMMIT (S9 §3.2). op.execute(""" CREATE OR REPLACE FUNCTION check_target_weight_sum() RETURNS trigger AS $$ DECLARE diff --git a/backend/alembic/versions/20260905_2010-2fe8f869c21b_add_s10_performance_fees.py b/backend/alembic/versions/20260905_2010-2fe8f869c21b_add_s10_performance_fees.py index e529e0a..52d70f2 100644 --- a/backend/alembic/versions/20260905_2010-2fe8f869c21b_add_s10_performance_fees.py +++ b/backend/alembic/versions/20260905_2010-2fe8f869c21b_add_s10_performance_fees.py @@ -4,14 +4,7 @@ Revises: 80985c1b5653 Create Date: 2026-09-05 20:10:00.000000 -S10 §3 (ADR 10): three new `account_role` values (`fees_accrued_payable`, `fee_revenue_accrued`, -`fee_revenue_collected`), plus six new tables -- `high_water_mark` (the one intentional exception to -append-only, a re-derivable cache), `fee_accrual` (append-only, `UNIQUE (customer_id, accrual_date)` -for job idempotency), `fee_charge` (`as_published_watermark` immutable once set, DB-trigger -enforced), `dunning_state`, `fee_restatement_disclosure` (append-only), and `payment_method` (not in -S10 §3's own schema list -- see `app/models/fees/payment_method.py`'s module docstring for why it -was added: closing a real gap, the same way `security`/`customer_cash_lock`/etc. were each added to -their owning spec before any code, per `DECISION-LOG.md`'s 2026-09-04 "Spec gaps closed" entry). +Add S10 performance fee account roles and six tables (S10 §3, ADR 10). """ from typing import Sequence, Union @@ -49,7 +42,7 @@ def upgrade() -> None: """Upgrade schema.""" - # --- S10's three new account roles (ADR 10) ------------------------------------------------- + # S10's three new account roles (ADR 10). with op.get_context().autocommit_block(): op.execute("ALTER TYPE account_role ADD VALUE IF NOT EXISTS 'fees_accrued_payable';") op.execute("ALTER TYPE account_role ADD VALUE IF NOT EXISTS 'fee_revenue_accrued';") @@ -58,7 +51,7 @@ def upgrade() -> None: op.drop_constraint(op.f("ck_account_role_dimension"), "account", type_="check") op.create_check_constraint(op.f("ck_account_role_dimension"), "account", _NEW_CONSTRAINT_SQL) - # --- high_water_mark (S10 §3.2) -- one row per customer, updated in place ------------------- + # high_water_mark (S10 §3.2) -- one row per customer, updated in place. op.create_table( 'high_water_mark', sa.Column('customer_id', sa.UUID(), nullable=False), @@ -76,7 +69,7 @@ def upgrade() -> None: ); """) - # --- fee_accrual (S10 §3.3) -- append-only, UNIQUE(customer_id, accrual_date) ---------------- + # fee_accrual (S10 §3.3) -- append-only, UNIQUE(customer_id, accrual_date). op.create_table( 'fee_accrual', sa.Column('id', sa.UUID(), nullable=False), @@ -100,7 +93,7 @@ def upgrade() -> None: """) op.execute("REVOKE UPDATE, DELETE ON fee_accrual FROM trueup_app, trueup_worker;") - # --- fee_charge (S10 §3.4) -------------------------------------------------------------------- + # fee_charge (S10 §3.4). op.create_table( 'fee_charge', sa.Column('id', sa.UUID(), nullable=False), @@ -125,9 +118,7 @@ def upgrade() -> None: OR customer_id = NULLIF(current_setting('app.customer_id', true), '')::uuid ); """) - # `as_published_watermark` is immutable once set (FR-47) -- enforced at the DB level, not only - # by application discipline (S10 §3.4's own required test: "attempt an UPDATE, assert it's - # rejected"). + # `as_published_watermark` is immutable once set, DB-enforced (FR-47). op.execute(""" CREATE OR REPLACE FUNCTION fee_charge_watermark_immutable() RETURNS trigger AS $$ BEGIN @@ -147,7 +138,7 @@ def upgrade() -> None: FOR EACH ROW EXECUTE FUNCTION fee_charge_watermark_immutable(); """) - # --- dunning_state (S10 §3.5) -- customer_id denormalized, matching approval_hold's precedent - + # dunning_state (S10 §3.5). op.create_table( 'dunning_state', sa.Column('fee_charge_id', sa.UUID(), nullable=False), @@ -169,7 +160,7 @@ def upgrade() -> None: ); """) - # --- fee_restatement_disclosure (S10 §6) -- append-only --------------------------------------- + # fee_restatement_disclosure (S10 §6) -- append-only. op.create_table( 'fee_restatement_disclosure', sa.Column('id', sa.UUID(), nullable=False), @@ -194,7 +185,7 @@ def upgrade() -> None: "REVOKE UPDATE, DELETE ON fee_restatement_disclosure FROM trueup_app, trueup_worker;" ) - # --- payment_method (S10 §7 -- not in S10 §3's literal schema list, see module docstring) ----- + # payment_method (S10 §7). op.create_table( 'payment_method', sa.Column('customer_id', sa.UUID(), nullable=False), @@ -245,9 +236,7 @@ def downgrade() -> None: sa.Enum(name='dunning_status').drop(op.get_bind(), checkfirst=True) sa.Enum(name='fee_charge_status').drop(op.get_bind(), checkfirst=True) - # The CHECK constraint must be dropped *before* the type rebuild, and only recreated *after* - # it -- Postgres binds a CHECK constraint's compiled literals to the column's enum type by OID - # at creation time (same ordering reason as e07a426f914f's downgrade). + # Drop the CHECK constraint before rebuilding the enum type it binds to by OID. op.drop_constraint(op.f("ck_account_role_dimension"), "account", type_="check") op.execute("ALTER TYPE account_role RENAME TO account_role_old;") diff --git a/backend/alembic/versions/20260905_2221-44100b4c0cae_add_fee_charge_unique_constraint_on_.py b/backend/alembic/versions/20260905_2221-44100b4c0cae_add_fee_charge_unique_constraint_on_.py index 76b1e59..c254e4a 100644 --- a/backend/alembic/versions/20260905_2221-44100b4c0cae_add_fee_charge_unique_constraint_on_.py +++ b/backend/alembic/versions/20260905_2221-44100b4c0cae_add_fee_charge_unique_constraint_on_.py @@ -4,12 +4,7 @@ Revises: c4a1e9f7b3d5 Create Date: 2026-09-05 22:21:13.132444 -F5 fix (S0 §10.1 audit): `FeeChargeService.create_pending_charge`'s idempotency was read-then- -insert only (`get_for_period` then `add`), so two concurrent or retried `MonthlyFeeChargeJob` runs -could race between the read and the insert and double-charge a customer for one billing period. -`fee_accrual` already gets this right (`uq_fee_accrual_customer_date`); this is the same DB-level -backstop for `fee_charge`, since `stripe_charge_id`'s existing uniqueness is nullable at creation -and does not close the gap. +F5 fix (S0 §10.1 audit): close a read-then-insert race that could double-charge a billing period. """ from typing import Sequence, Union diff --git a/backend/alembic/versions/20260905_2228-38096a12c976_harden_money_row_immutability_and_.py b/backend/alembic/versions/20260905_2228-38096a12c976_harden_money_row_immutability_and_.py index 629d5fd..d2f47e1 100644 --- a/backend/alembic/versions/20260905_2228-38096a12c976_harden_money_row_immutability_and_.py +++ b/backend/alembic/versions/20260905_2228-38096a12c976_harden_money_row_immutability_and_.py @@ -4,27 +4,8 @@ Revises: 44100b4c0cae Create Date: 2026-09-05 22:28:16.626996 -F12/I3/I9 fixes (S0 §10.1 audit). Two independent gaps, both against the automatic-fail rule -"UPDATE or DELETE on money rows. Anywhere. Ever." and S0 §7.3's tenant-isolation requirement: - -- The entire S5 migration (tax_lot/lot_consumption/wash_sale_adjustment) shipped with no REVOKE - statements at all, unlike every other money-bearing table in the schema. `tax_lot`/ - `lot_consumption` are documented mutable projections (UPDATE stays legitimate) but must never be - deleted; `wash_sale_adjustment` is itself an immutable correction record and gets the full - REVOKE UPDATE, DELETE every other immutable ledger table has. `approval_hold` (S3), - `high_water_mark` and `fee_charge` (S10) had the same DELETE gap -- `fee_charge`'s own - `as_published_watermark` column is already protected by a trigger, but the row itself was never - protected from deletion. -- `idempotency_key` stores a customer's cached response body (financial PII) and is tenant-scoped - by `customer_id`, but was the only such table in the schema with no Row-Level Security policy at - all -- every one of its 23 siblings has one. Added the identical `tenant_isolation` predicate - every other table uses. - -Each corresponding model file (`app/models/...`) now also carries the equivalent -`event.listen(..., "after_create", DDL(...))` hook, matching this codebase's established pattern -of applying the same grant/policy DDL whether a table is created by this migration or by -SQLAlchemy metadata directly (the test suite's own path) -- see `journal_entry.py`'s identical -precedent, cited in its own comment. +F12/I3/I9 fixes (S0 §10.1 audit): revoke missing DELETE grants on money rows and add RLS to +idempotency_key, which had none. """ from typing import Sequence, Union diff --git a/backend/alembic/versions/20260906_0300-c4a1e9f7b3d5_add_bank_link_and_kyc_session_tables.py b/backend/alembic/versions/20260906_0300-c4a1e9f7b3d5_add_bank_link_and_kyc_session_tables.py index 83c06ef..5578019 100644 --- a/backend/alembic/versions/20260906_0300-c4a1e9f7b3d5_add_bank_link_and_kyc_session_tables.py +++ b/backend/alembic/versions/20260906_0300-c4a1e9f7b3d5_add_bank_link_and_kyc_session_tables.py @@ -4,12 +4,7 @@ Revises: 2fe8f869c21b Create Date: 2026-09-06 03:00:00.000000 -`app/models/identity/bank_link.py` and `app/models/identity/kyc_session.py` (S2 §3.2/§3.3, added in -Wave 4) were never given a matching migration -- confirmed by running `alembic upgrade head` against -a clean database and finding both tables absent. Both models, their repositories, and their RLS/ -trigger DDL already exist and are already exercised by `tests/integration/test_bank_link.py`/ -`test_kyc_session.py` and the funding/identity API tests; this migration only catches the schema up -to what the models have already specified for several waves, with no model change of its own. +bank_link and kyc_session (S2 §3.2/§3.3) were missing their migration; catches the schema up. """ from typing import Sequence, Union @@ -75,8 +70,7 @@ def upgrade() -> None: sa.UniqueConstraint('provider_session_id', name=op.f('uq_kyc_session_provider_session_id')), ) - # --- kyc_session: status transitions exactly once, pending -> terminal (S2 §3.2), same shape - # as settlement_obligation_single_transition (S1 §6) --- + # kyc_session: status transitions exactly once, pending -> terminal (S2 §3.2). op.execute(""" CREATE OR REPLACE FUNCTION kyc_session_single_transition() RETURNS trigger AS $$ BEGIN @@ -93,7 +87,7 @@ def upgrade() -> None: FOR EACH ROW EXECUTE FUNCTION kyc_session_single_transition(); """) - # --- RLS: role-aware tenant isolation (S0 §7.3, ADR 17), same shape as customer/account --- + # RLS tenant isolation (S0 §7.3, ADR 17). op.execute(""" ALTER TABLE bank_link ENABLE ROW LEVEL SECURITY; CREATE POLICY tenant_isolation ON bank_link @@ -110,9 +104,7 @@ def upgrade() -> None: ); """) - # --- both are regulatory-relevant records (what funding moved through, what a KYC review saw) - # -- DELETE is revoked for both runtime roles; UPDATE stays granted for bank_link's status - # transitions and kyc_session's one-time transition the trigger above polices. + # Regulatory records -- DELETE revoked for both runtime roles. op.execute(""" REVOKE DELETE ON bank_link FROM trueup_app, trueup_worker; REVOKE DELETE ON kyc_session FROM trueup_app, trueup_worker; diff --git a/backend/alembic/versions/20260906_0424-670073c5146c_add_s13_agent_surface.py b/backend/alembic/versions/20260906_0424-670073c5146c_add_s13_agent_surface.py new file mode 100644 index 0000000..56d3642 --- /dev/null +++ b/backend/alembic/versions/20260906_0424-670073c5146c_add_s13_agent_surface.py @@ -0,0 +1,114 @@ +"""add S13 agent surface + +Revision ID: 670073c5146c +Revises: 79c5ef5459fa +Create Date: 2026-09-06 04:24:00.412052 + +""" +from collections.abc import Sequence + +import sqlalchemy as sa +from sqlalchemy.dialects import postgresql + +from alembic import op + +# revision identifiers, used by Alembic. +revision: str = '670073c5146c' +down_revision: str | Sequence[str] | None = '79c5ef5459fa' +branch_labels: str | Sequence[str] | None = None +depends_on: str | Sequence[str] | None = None + + +def upgrade() -> None: + """Upgrade schema.""" + # ### commands auto generated by Alembic - please adjust! ### + op.create_table('agent_action_request', + sa.Column('id', sa.UUID(), nullable=False), + sa.Column('action', sa.Enum('resolve_break', 'kyc_override', 'rebalance', name='agent_action_type'), nullable=False), + sa.Column('arguments', postgresql.JSONB(astext_type=sa.Text()), nullable=False), + sa.Column('requesting_agent', sa.String(), nullable=False), + sa.Column('justification', sa.String(), nullable=False), + sa.Column('status', sa.Enum('pending', 'approved', 'rejected', 'executed', 'execution_failed', name='agent_action_status'), server_default='pending', nullable=False), + sa.Column('reviewed_by', sa.UUID(), nullable=True), + sa.Column('reviewed_at', sa.DateTime(timezone=True), nullable=True), + sa.Column('review_note', sa.String(), nullable=True), + sa.Column('execution_error', sa.String(), nullable=True), + sa.Column('executed_at', sa.DateTime(timezone=True), nullable=True), + sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False), + sa.CheckConstraint("(status <> 'executed') OR (executed_at IS NOT NULL)", name=op.f('ck_agent_action_request_executed_requires_timestamp')), + sa.CheckConstraint("(status <> 'execution_failed') OR (execution_error IS NOT NULL)", name=op.f('ck_agent_action_request_failure_requires_error')), + sa.CheckConstraint("(status NOT IN ('approved','rejected')) OR (reviewed_by IS NOT NULL AND reviewed_at IS NOT NULL)", name=op.f('ck_agent_action_request_review_requires_reviewer')), + sa.CheckConstraint('length(justification) > 0', name=op.f('ck_agent_action_request_justification_present')), + sa.PrimaryKeyConstraint('id', name=op.f('pk_agent_action_request')) + ) + op.create_index('ix_agent_action_request_status_created', 'agent_action_request', ['status', 'created_at'], unique=False) + op.create_table('staff_api_token', + sa.Column('id', sa.UUID(), nullable=False), + sa.Column('staff_id', sa.UUID(), nullable=False), + sa.Column('label', sa.String(), nullable=False), + sa.Column('token_hash', sa.String(length=64), nullable=False), + sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False), + sa.Column('revoked_at', sa.DateTime(timezone=True), nullable=True), + sa.PrimaryKeyConstraint('id', name=op.f('pk_staff_api_token')), + sa.UniqueConstraint('token_hash', name=op.f('uq_staff_api_token_token_hash')) + ) + op.create_index(op.f('ix_staff_api_token_staff_id'), 'staff_api_token', ['staff_id'], unique=False) + # ### end Alembic commands ### + + # Single-transition guard: pending -> {approved, rejected} -> {executed, execution_failed} (S13 §3.1, ADR 24). + op.execute(""" + CREATE OR REPLACE FUNCTION agent_action_request_single_transition() RETURNS trigger AS $$ + BEGIN + IF OLD.status = 'pending' THEN + IF NEW.status NOT IN ('approved', 'rejected') THEN + RAISE EXCEPTION + 'agent_action_request % may only move from pending to approved or rejected (got %)', + OLD.id, NEW.status; + END IF; + ELSIF OLD.status = 'approved' THEN + IF NEW.status NOT IN ('executed', 'execution_failed') THEN + RAISE EXCEPTION + 'agent_action_request % may only move approved -> executed/execution_failed (got %)', + OLD.id, NEW.status; + END IF; + ELSE + RAISE EXCEPTION 'agent_action_request % is already terminal (%) and cannot be updated', + OLD.id, OLD.status; + END IF; + IF NEW.action <> OLD.action + OR NEW.arguments IS DISTINCT FROM OLD.arguments + OR NEW.requesting_agent <> OLD.requesting_agent + OR NEW.justification <> OLD.justification + OR NEW.created_at <> OLD.created_at THEN + RAISE EXCEPTION + 'agent_action_request % identifying fields are immutable once created (S13 section 3.1)', + OLD.id; + END IF; + RETURN NEW; + END; + $$ LANGUAGE plpgsql; + + CREATE TRIGGER agent_action_request_before_update + BEFORE UPDATE ON agent_action_request + FOR EACH ROW EXECUTE FUNCTION agent_action_request_single_transition(); + """) + + # Append-only in spirit (ADR 24): DELETE revoked for both runtime credentials. + op.execute("REVOKE DELETE ON agent_action_request FROM trueup_app, trueup_worker;") + + # No RLS on either table (S13 §3.1/§3.2): access control is @requires_role on every route. + + +def downgrade() -> None: + """Downgrade schema.""" + op.execute("DROP TRIGGER IF EXISTS agent_action_request_before_update ON agent_action_request;") + op.execute("DROP FUNCTION IF EXISTS agent_action_request_single_transition();") + + # ### commands auto generated by Alembic - please adjust! ### + op.drop_index(op.f('ix_staff_api_token_staff_id'), table_name='staff_api_token') + op.drop_table('staff_api_token') + op.drop_index('ix_agent_action_request_status_created', table_name='agent_action_request') + op.drop_table('agent_action_request') + # ### end Alembic commands ### + sa.Enum(name='agent_action_status').drop(op.get_bind(), checkfirst=True) + sa.Enum(name='agent_action_type').drop(op.get_bind(), checkfirst=True) diff --git a/backend/app/__init__.py b/backend/app/__init__.py index 15a5aad..346e460 100644 --- a/backend/app/__init__.py +++ b/backend/app/__init__.py @@ -1,12 +1,4 @@ -"""Flask application factory. - -Wires the layers S0 §3 defines into one application. Everything below is cross-cutting setup; -no business logic lives here. - -Wave 0 establishes the factory, security headers, the RFC 9457 error contract, correlation IDs, -and the cipher installation. Authentication, sessions and CSRF are wired in alongside the auth -surface, which owns their configuration. -""" +"""Flask application factory (S0 §3). Cross-cutting setup only, no business logic.""" from __future__ import annotations @@ -17,9 +9,11 @@ from werkzeug.exceptions import HTTPException from app.config import Settings, get_settings +from app.controllers.admin.agent_requests import agent_requests_bp from app.controllers.admin.customers import admin_customers_bp from app.controllers.admin.kyc_overrides import admin_kyc_overrides_bp from app.controllers.admin.rebalance import admin_rebalance_bp +from app.controllers.admin.staff_api_tokens import staff_api_tokens_bp from app.controllers.api.auth import auth_bp, init_auth from app.controllers.api.breaks import breaks_bp from app.controllers.api.chat import chat_bp @@ -52,8 +46,7 @@ log = get_logger(__name__) -# Content-Security-Policy for a JSON API: it serves no HTML and loads nothing, so everything is -# denied. The frontend is a separate origin with its own policy. +# CSP for a JSON API: serves no HTML, everything denied. _CSP = { "default-src": "'none'", "frame-ancestors": "'none'", @@ -66,14 +59,12 @@ def create_app(settings: Settings | None = None) -> Flask: settings = settings or get_settings() app = Flask(__name__) app.config["TRUEUP_SETTINGS"] = settings - # Signs the session cookie and every CSRF token (S0 §7.1) — Flask and Flask-WTF both refuse - # to operate without one, by design, rather than falling back to an unsigned/predictable key. + # Signs the session cookie and every CSRF token (S0 §7.1). app.config["SECRET_KEY"] = settings.secret_key.get_secret_value() app.config["PROPAGATE_EXCEPTIONS"] = False - # Rate-limit counters live in Redis so limits hold across every container replica; an - # in-memory counter would give each replica its own budget (S0 §7.4, API4). + # Redis-backed so limits hold across replicas (S0 §7.4, API4). app.config["RATELIMIT_STORAGE_URI"] = settings.redis_url - app.config["RATELIMIT_HEADERS_ENABLED"] = True # Retry-After on 429, per root CLAUDE.md + app.config["RATELIMIT_HEADERS_ENABLED"] = True # Retry-After on 429 configure_logging( json_output=settings.flask_env != "development", @@ -115,24 +106,18 @@ def create_app(settings: Settings | None = None) -> Flask: app.register_blueprint(admin_rebalance_bp) app.register_blueprint(admin_customers_bp) app.register_blueprint(admin_kyc_overrides_bp) + app.register_blueprint(agent_requests_bp) + app.register_blueprint(staff_api_tokens_bp) app.register_blueprint(stripe_identity_bp) app.register_blueprint(plaid_webhooks_bp) app.register_blueprint(fees_bp) app.register_blueprint(stripe_billing_bp) - # `flask jobs ` (Makefile's `job` target; the Azure Container Apps Job the deployed - # scheduled jobs run as) has no other entrypoint -- confirmed missing: register_cli existed - # but nothing ever called it, so every job command was unreachable outside a direct unit test. register_cli(app) return app def _build_cipher(settings: Settings) -> Cipher: - """Select the Cipher adapter (ADR 23). - - Key Vault wherever it is configured. The local adapter is refused in production outright — a - production deployment silently falling back to a config-supplied key is exactly the - "insecure fallback" S0 §12 forbids. - """ + """Select the Cipher adapter; local adapter refused in production (ADR 23).""" if settings.has_key_vault_cipher: from app.integrations.azure.keyvault_cipher import KeyVaultCipher @@ -168,16 +153,10 @@ def _echo_correlation_id(response: Response) -> Response: def _register_error_handlers(app: Flask) -> None: - """Every error leaves as RFC 9457 `application/problem+json` (S0 §8). - - The body carries a stable machine-readable `code` a frontend can branch on, and never a stack - trace, SQL fragment, or internal identifier. - """ + """Every error leaves as RFC 9457 `application/problem+json` (S0 §8).""" @app.errorhandler(AppError) def _app_error(exc: AppError) -> tuple[Any, int]: - # The hierarchy already knows its own status, title and stable code; the only thing the - # request layer adds is the correlation ID. `detail` stays server-side by construction. return _render(exc.to_problem(g.get("correlation_id", "")), exc.status) @app.errorhandler(HTTPException) @@ -190,8 +169,7 @@ def _http_error(exc: HTTPException) -> tuple[Any, int]: @app.errorhandler(Exception) def _unexpected_error(exc: Exception) -> tuple[Any, int]: - # Logged in full server-side; the client is told nothing beyond the correlation ID, which - # is what lets support join a customer's report to this exact trace. + # Logged in full server-side; client gets only the correlation ID. log.error("unhandled_exception", exc_info=exc) return _problem(status=500, title="Internal Server Error", code="internal_error") diff --git a/backend/app/config.py b/backend/app/config.py index 6f8a559..11f7215 100644 --- a/backend/app/config.py +++ b/backend/app/config.py @@ -1,13 +1,6 @@ -"""Application settings. +"""Application settings, read only through this module (S0 §12). -Every configurable value in the backend is read through this module — never `os.environ` inline, -never a hard-coded literal (S0 §12, `backend/CLAUDE.md`). Two rules shape what follows: - -1. **No secret has a default.** A missing required value raises at construction, so the process - fails to start rather than running with an insecure fallback (S0 §7.4, OWASP A05). -2. **Provider credentials are optional.** They are absent until the sandbox accounts are created; - the app still starts, and each real adapter refuses to operate without its own keys. That keeps - a missing Plaid key from blocking the ledger, while never silently substituting a fake. +No secret has a default; provider credentials are optional until sandbox accounts exist. """ from __future__ import annotations @@ -36,29 +29,26 @@ class Settings(BaseSettings): # --- Core (required; no defaults) --------------------------------------------------------- secret_key: SecretStr = Field(min_length=32) - """Session signing key. 32 chars minimum — a short key is a weak signature, not a style nit.""" + """Session signing key, 32 chars minimum.""" database_url: SecretStr - """Web API credential. Must map to a role WITHOUT BYPASSRLS (S0 §7.3).""" + """Web API DB credential (non-BYPASSRLS role, S0 §7.3).""" database_url_worker: SecretStr - """Jobs and outbox worker. The BYPASSRLS role, deliberately a separate credential.""" + """Jobs/outbox worker DB credential (BYPASSRLS role).""" database_url_owner: SecretStr - """Schema owner. Runs migrations only; never serves a request.""" + """Schema-owner credential; migrations only, never serves a request.""" database_url_chat: SecretStr - """`chat_readonly`'s own credential (ADR 19) — granted `SELECT` on the curated chat views only, - a narrower and separately-provisioned role than `APP`'s. Required, no default, matching the - other three role credentials above: a missing value must fail startup, never silently fall - back to a broader-privileged connection for the LLM's tool calls.""" + """`chat_readonly` credential, scoped to curated chat views (ADR 19).""" redis_url: str - """Sessions and rate-limit counters only. Never financial state (ADR 13).""" + """Sessions and rate-limit counters only, never financial state (ADR 13).""" # --- Runtime posture ---------------------------------------------------------------------- flask_env: Environment = "production" - """Defaults to production so an unset value fails secure, not open.""" + """Defaults to production so an unset value fails secure.""" flask_debug: bool = False @@ -66,7 +56,7 @@ class Settings(BaseSettings): azure_key_vault_url: str | None = None azure_keyvault_wrap_key_name: str | None = None local_cipher_key: SecretStr | None = None - """Base64 32-byte key for LocalDevCipher. Ignored when a Key Vault wrap key is configured.""" + """Base64 32-byte LocalDevCipher key; ignored when Key Vault is configured.""" # --- Provider credentials (optional until the sandbox accounts exist) --------------------- alpaca_api_key_id: SecretStr | None = None @@ -81,84 +71,57 @@ class Settings(BaseSettings): stripe_webhook_secret_identity: SecretStr | None = None stripe_webhook_secret_billing: SecretStr | None = None stripe_publishable_key: str | None = None - """Not a `SecretStr` -- a Stripe publishable key is explicitly meant to be embedded in - client-side code (Stripe's own naming), unlike every other credential in this section. The - frontend's Stripe.js `verifyIdentity(client_secret)` call needs it and has no other way to - obtain it (`GET /api/v1/identity/config`).""" + """Stripe publishable key; safe for client-side embedding, unlike other creds here.""" openai_api_key: SecretStr | None = None openai_org_id: str | None = None openai_chat_model: str = "gpt-4o-mini" - """S11/ADR 18: a tunable setting, not an architectural decision — start cost-efficient, upgrade - only if answer quality demands it (NFR-11's six-week budget).""" + """Chat completion model id (S11/ADR 18).""" chat_daily_query_cap: int = 50 - """S11 §5.2/NFR-16 — per-customer, per-day cap on chat turns, independent of the per-turn tool - iteration cap below. A conservative default, adjustable without a code change.""" + """Per-customer daily chat turn cap (S11 §5.2/NFR-16).""" chat_max_tool_iterations: int = 6 - """S11 §5.2/NFR-16 — bounds a single turn's tool-calling loop, independent of the daily cap: - caps one confused turn's cost and rules out an infinite tool-calling loop.""" + """Per-turn tool-call iteration cap (S11 §5.2/NFR-16).""" - # --- Business tunables (S2/S3 — defensible engineering defaults, not compliance sign-offs; - # flagged for review against actual NACHA/ACH limits before go-live, S2 §5.2) -------------- + # --- Business tunables (S2/S3 — review before go-live, S2 §5.2) --------------------------- kyc_max_attempts: int = 3 - """S2 §3.2: after this many rejected `kyc_session` attempts, `customer.kyc_status` locks to - `rejected` and requires manual adviser override to reopen.""" + """Rejected KYC attempts before `customer.kyc_status` locks to `rejected` (S2 §3.2).""" deposit_cap_per_transaction: Money = Money("25000.00") deposit_cap_per_day: Money = Money("50000.00") - """S2 §5.2 step 2. Per-customer, per-transaction and daily-aggregate caps.""" + """Per-customer transaction and daily deposit caps (S2 §5.2 step 2).""" order_approval_threshold_usd: Money = Money("10000.00") - """S3 §4: an order's notional strictly above this requires explicit customer approval - (`draft -> awaiting_approval`) before it can be submitted; at or below, `draft -> approved` - is immediate. `> threshold`, not `>=` — S3 §7 case 6 states the boundary explicitly.""" + """Order notional strictly above this requires customer approval (S3 §4, S3 §7 case 6).""" drift_band_pct: Decimal = Decimal("0.05") - """S9 §5: relative tolerance band, evaluated per holding against its own target weight (a - 20%-target holding triggers at 19%/21%, not a flat +/-5 percentage-point band). `> band` - triggers; `== band` does not (S9 §9's documented boundary).""" + """Relative drift tolerance per holding before rebalance triggers (S9 §5, §9).""" rebalance_cash_buffer_pct: Decimal = Decimal("0.01") - """S9 §5: fraction of portfolio value held back from every rebalance run's total buy sizing, - absorbing price movement between the drift-check computation and the order's actual fill.""" + """Cash fraction withheld from rebalance buy sizing (S9 §5).""" fee_rate_pct: Decimal - """S10 §1/§10: the performance fee rate, a fraction (e.g. `0.02` for 2%), applied to TWR-derived - gain above the high-water-mark. Required with **no default** -- a deliberate business decision - the spec itself declines to invent (`docs/decisions/10-performance-fee-twr-high-water-mark.md`). - Set to `0.0` for now (`DECISION-LOG.md`, 2026-09-05): a real, explicit rate that happens to be - zero, not an absent one -- `DailyFeeAccrualJob` still runs and records true `gain_amount` - figures even while `fee_amount` is zero.""" + """Performance fee rate on TWR gain above high-water-mark; no default by design + (S10 §1/§10, DECISION-LOG.md 2026-09-05).""" dunning_max_attempts: int = 4 - """S10 §3.5: `DUNNING_MAX_ATTEMPTS`, a tunable setting -- after this many failed retries a - `fee_charge` moves to `dunning`/`exhausted`, a standing customer-visible balance owed - (FR-48).""" + """Failed retries before a `fee_charge` moves to `dunning`/`exhausted` (S10 §3.5, FR-48).""" dunning_backoff_base_hours: int = 24 - """S10 §5: the base of `DunningService`'s exponential backoff (`base * 2**(attempt - 1)` - hours) between retry attempts -- a defensible engineering default, flagged for business review - before go-live, same posture as `KYC_MAX_ATTEMPTS`/the deposit caps.""" + """Base hours for `DunningService`'s exponential backoff (S10 §5).""" outbox_max_attempts: int = 5 - """S0 §9: how many times `OutboxWorker` retries a `job_outbox` row (exponential backoff, - `2**(attempt-1)` seconds) before moving it to `dead_letter` for operator attention -- the same - tunable-with-a-default posture as `dunning_max_attempts` above.""" + """Retries before an outbox row moves to `dead_letter` (S0 §9).""" + + mcp_server_host: str = "0.0.0.0" # noqa: S104 # nosec B104 -- container's only interface. + mcp_server_port: int = 8001 + """MCP server bind port, separate from Flask's 8000 (S13/ADR 24).""" @model_validator(mode="before") @classmethod def _blank_is_unset(cls, data: Any) -> Any: - """Treat `KEY=` in a .env file as absent, not as an empty value. - - `.env.example` ships every optional credential blank, so without this an empty - `AZURE_KEY_VAULT_URL` reads as "Key Vault is configured" and the app tries to reach a - vault at "", and a blank `ALPACA_API_KEY_ID` reads as a real key. Dropping the key rather - than mapping it to `None` is what makes all three cases correct at once: optionals fall - back to `None`, fields with a default keep their default, and a required setting still - fails as missing. - """ + """Treat `KEY=` in a .env file as absent, not as an empty value.""" if not isinstance(data, dict): return data return { @@ -169,7 +132,7 @@ def _blank_is_unset(cls, data: Any) -> Any: @model_validator(mode="after") def _debug_only_in_development(self) -> Settings: - """OWASP A05. Debug mode leaks stack traces and enables the Werkzeug console.""" + """OWASP A05: debug mode is permitted only in development.""" if self.flask_debug and self.flask_env != "development": raise ValueError( f"flask_debug cannot be enabled when flask_env is {self.flask_env!r}; " @@ -225,6 +188,5 @@ def has_key_vault_cipher(self) -> bool: @lru_cache(maxsize=1) def get_settings() -> Settings: - """Process-wide settings. Cached so the .env file is read once, not per request.""" - # Values come from the environment and the .env file, not from call arguments. + """Process-wide settings, cached so .env is read once.""" return Settings() diff --git a/backend/app/controllers/admin/agent_requests.py b/backend/app/controllers/admin/agent_requests.py new file mode 100644 index 0000000..0240b24 --- /dev/null +++ b/backend/app/controllers/admin/agent_requests.py @@ -0,0 +1,334 @@ +"""Human approval queue for MCP write-tool proposals (S13 §5). Adviser/admin-only. + +`approve` executes the row's mapped service call inside a `SAVEPOINT`: an expected domain failure +marks the row `execution_failed` without losing the `approved` transition; an unexpected one +propagates as a normal 500 (ADR 24 point 3). +""" + +from __future__ import annotations + +import uuid +from collections.abc import Callable +from datetime import UTC, datetime +from typing import Any + +from flask import Blueprint, jsonify, request +from flask_login import current_user +from pydantic import BaseModel, Field +from pydantic import ValidationError as PydanticValidationError + +from app.config import get_settings +from app.core.clock import MarketClock +from app.core.errors import ConflictError, NotFoundError, ValidationError +from app.core.pagination import decode_cursor, normalize_limit, paginate +from app.core.security import audited, requires_role +from app.core.uow import SessionRole +from app.extensions import limiter +from app.models.identity.customer import KycStatus +from app.models.marketdata.trading_calendar import ( + CachedTradingCalendar, + MarketCalendarCacheMissError, +) +from app.models.ops.agent_action_request import ( + AgentActionRequest, + AgentActionStatus, + AgentActionType, + InvalidAgentActionTransitionError, +) +from app.models.reconciliation.reconciliation_break import AlreadyResolvedError +from app.services.agent_surface.uow import AgentSurfaceUnitOfWork +from app.services.ledger.cash_policy_service import CashPolicyService +from app.services.orders.approval_hold_service import ApprovalHoldService +from app.services.orders.holds_provider import OrderHoldsProvider +from app.services.orders.order_service import CustomerNotEligibleError, OrderService +from app.services.rebalance.drift_evaluation_service import ( + DriftEvaluationService, + NoAssignedModelError, +) +from app.services.rebalance.rebalance_order_service import RebalanceOrderService, real_order_placer +from app.views.agent_requests import AgentActionRequestResponse, AgentActionRequestsListResponse + +agent_requests_bp = Blueprint( + "admin_agent_requests", __name__, url_prefix="/api/v1/admin/agent-requests" +) + +_STAFF_ROLES = ("adviser", "admin") + +_EXPECTED_EXECUTION_ERRORS: tuple[type[Exception], ...] = ( + AlreadyResolvedError, + NoAssignedModelError, + CustomerNotEligibleError, + # Operational timing condition, not a bug -- treated as expected, like the three above. + MarketCalendarCacheMissError, +) + + +class _ExecutionFailedError(RuntimeError): + """A precondition an `_execute_*` mapping checks itself; caught the same way as + `_EXPECTED_EXECUTION_ERRORS` (S13 §6 edge case 1).""" + + +class _ReviewRequest(BaseModel): + review_note: str | None = None + + +class _RejectRequest(BaseModel): + review_note: str = Field(min_length=1) + + +def _to_response(row: AgentActionRequest) -> AgentActionRequestResponse: + return AgentActionRequestResponse( + id=row.id, + action=row.action.value, + arguments=row.arguments, + requesting_agent=row.requesting_agent, + justification=row.justification, + status=row.status.value, + reviewed_by=row.reviewed_by, + reviewed_at=row.reviewed_at, + review_note=row.review_note, + execution_error=row.execution_error, + executed_at=row.executed_at, + created_at=row.created_at, + ) + + +def _target_customer_id(row: AgentActionRequest) -> uuid.UUID | None: + raw = row.arguments.get("customer_id") + return uuid.UUID(raw) if raw is not None else None + + +def _decode_request_cursor(raw: str) -> tuple[datetime, uuid.UUID]: + decoded = decode_cursor(raw) + if len(decoded) != 2 or not isinstance(decoded[0], str) or not isinstance(decoded[1], str): + raise ValidationError("invalid pagination cursor") + try: + return datetime.fromisoformat(decoded[0]), uuid.UUID(decoded[1]) + except ValueError as exc: + raise ValidationError("invalid pagination cursor") from exc + + +@agent_requests_bp.route("", methods=["GET"]) +@limiter.limit("60 per minute") +@requires_role(*_STAFF_ROLES) +def list_requests() -> Any: + raw_status = request.args.get("status", AgentActionStatus.PENDING.value) + try: + status = AgentActionStatus(raw_status) + except ValueError as exc: + raise ValidationError(f"unknown status {raw_status!r}") from exc + + raw_limit = request.args.get("limit") + limit = normalize_limit(int(raw_limit)) if raw_limit is not None else normalize_limit(None) + after: tuple[datetime, uuid.UUID] | None = None + raw_cursor = request.args.get("cursor") + if raw_cursor: + after = _decode_request_cursor(raw_cursor) + + with AgentSurfaceUnitOfWork(customer_id=None, role=SessionRole(current_user.role)) as uow: + rows = uow.agent_action_requests.list_by_status(status, limit=limit, after=after) + page = paginate( + rows, limit=limit, cursor_key=lambda r: (r.created_at.isoformat(), str(r.id)) + ) + + view = AgentActionRequestsListResponse( + requests=[_to_response(row) for row in page.items], next_cursor=page.next_cursor + ) + + return jsonify(view.model_dump(mode="json")), 200 + + +@agent_requests_bp.route("/", methods=["GET"]) +@limiter.limit("60 per minute") +@requires_role(*_STAFF_ROLES) +def get_request(request_id: uuid.UUID) -> Any: + with AgentSurfaceUnitOfWork(customer_id=None, role=SessionRole(current_user.role)) as uow: + row = uow.agent_action_requests.get_by_id(request_id) + if row is None: + raise NotFoundError(f"agent_action_request {request_id} not found") + view = _to_response(row) + + return jsonify(view.model_dump(mode="json")), 200 + + +@agent_requests_bp.route("//approve", methods=["POST"]) +@limiter.limit("30 per minute") +@requires_role(*_STAFF_ROLES) +def approve(request_id: uuid.UUID) -> Any: + try: + body = _ReviewRequest.model_validate(request.get_json(silent=True) or {}) + except PydanticValidationError as exc: + raise ValidationError(str(exc)) from exc + + now = datetime.now(UTC) + with AgentSurfaceUnitOfWork(customer_id=None, role=SessionRole(current_user.role)) as uow: + row = uow.agent_action_requests.get_for_update(request_id) + if row is None: + raise NotFoundError(f"agent_action_request {request_id} not found") + + _approve_request( + uow=uow, + target_customer_id=_target_customer_id(row), + row=row, + reviewed_by=current_user.id, + reviewed_at=now, + review_note=body.review_note, + ) + uow.commit() + view = _to_response(row) + + return jsonify(view.model_dump(mode="json")), 200 + + +@agent_requests_bp.route("//reject", methods=["POST"]) +@limiter.limit("30 per minute") +@requires_role(*_STAFF_ROLES) +def reject(request_id: uuid.UUID) -> Any: + try: + body = _RejectRequest.model_validate(request.get_json(silent=True) or {}) + except PydanticValidationError as exc: + raise ValidationError(str(exc)) from exc + + now = datetime.now(UTC) + with AgentSurfaceUnitOfWork(customer_id=None, role=SessionRole(current_user.role)) as uow: + row = uow.agent_action_requests.get_for_update(request_id) + if row is None: + raise NotFoundError(f"agent_action_request {request_id} not found") + + _reject_request( + uow=uow, + target_customer_id=_target_customer_id(row), + row=row, + reviewed_by=current_user.id, + reviewed_at=now, + review_note=body.review_note, + ) + uow.commit() + view = _to_response(row) + + return jsonify(view.model_dump(mode="json")), 200 + + +@audited("agent_action_request.approve", target_customer_id_param="target_customer_id") +def _approve_request( + *, + uow: AgentSurfaceUnitOfWork, + target_customer_id: uuid.UUID | None, + row: AgentActionRequest, + reviewed_by: uuid.UUID, + reviewed_at: datetime, + review_note: str | None, +) -> None: + """Indirection so `@audited` sees `uow`/`target_customer_id` as its own arguments.""" + try: + uow.agent_action_requests.approve( + row, reviewed_by=reviewed_by, reviewed_at=reviewed_at, review_note=review_note + ) + except InvalidAgentActionTransitionError as exc: + raise ConflictError(str(exc), code="agent_action_request_not_pending") from exc + + try: + with uow.session.begin_nested(): + _EXECUTORS[row.action](uow, row, reviewed_by, reviewed_at) + except _EXPECTED_EXECUTION_ERRORS as exc: + uow.agent_action_requests.mark_execution_failed(row, execution_error=str(exc)) + else: + uow.agent_action_requests.mark_executed(row, executed_at=reviewed_at) + + +@audited("agent_action_request.reject", target_customer_id_param="target_customer_id") +def _reject_request( + *, + uow: AgentSurfaceUnitOfWork, + target_customer_id: uuid.UUID | None, + row: AgentActionRequest, + reviewed_by: uuid.UUID, + reviewed_at: datetime, + review_note: str, +) -> None: + """Indirection so `@audited` sees `uow`/`target_customer_id` as its own arguments.""" + try: + uow.agent_action_requests.reject( + row, reviewed_by=reviewed_by, reviewed_at=reviewed_at, review_note=review_note + ) + except InvalidAgentActionTransitionError as exc: + raise ConflictError(str(exc), code="agent_action_request_not_pending") from exc + + +def _execute_resolve_break( + uow: AgentSurfaceUnitOfWork, + row: AgentActionRequest, + reviewed_by: uuid.UUID, + reviewed_at: datetime, +) -> None: + """S13 §5.1: the same service `POST /admin/breaks//resolve` already calls.""" + break_id = uuid.UUID(row.arguments["break_id"]) + break_row = uow.reconciliation_breaks.get_by_id(break_id) + if break_row is None: + raise _ExecutionFailedError(f"reconciliation_break {break_id} not found") + uow.reconciliation_breaks.resolve( + break_row, + resolved_by=reviewed_by, + resolved_at=reviewed_at, + resolution_note=row.arguments["resolution_note"], + ) + + +def _execute_kyc_override( + uow: AgentSurfaceUnitOfWork, + row: AgentActionRequest, + reviewed_by: uuid.UUID, + reviewed_at: datetime, +) -> None: + """S13 §5.1: the same service `POST /admin/kyc-overrides/` calls.""" + customer_id = uuid.UUID(row.arguments["customer_id"]) + customer = uow.customers.get_by_id(customer_id) + if customer is None: + raise _ExecutionFailedError(f"customer {customer_id} not found") + customer.kyc_status = KycStatus.pending + + +def _execute_rebalance( + uow: AgentSurfaceUnitOfWork, + row: AgentActionRequest, + reviewed_by: uuid.UUID, + reviewed_at: datetime, +) -> None: + """S13 §5.1: `DriftEvaluationService.evaluate` + the same order-placement path + `MonthlyRebalanceJob` uses, for this one customer only.""" + customer_id = uuid.UUID(row.arguments["customer_id"]) + if uow.customers.get_by_id(customer_id) is None: + raise _ExecutionFailedError(f"customer {customer_id} not found") + + settings = get_settings() + clock = MarketClock(CachedTradingCalendar(uow.calendar_cache)) + as_of_date = clock.market_date(datetime.now(UTC)) + + drift_evaluator = DriftEvaluationService(uow, drift_band_pct=settings.drift_band_pct) + cash_policy = CashPolicyService(uow, holds_provider=OrderHoldsProvider(uow)) + order_service = OrderService( + uow, + hold_service=ApprovalHoldService(uow), + cash_policy=cash_policy, + approval_threshold_usd=settings.order_approval_threshold_usd, + ) + rebalance_orders = RebalanceOrderService( + order_placer=real_order_placer(order_service), + cash_provider=cash_policy, + cash_buffer_pct=settings.rebalance_cash_buffer_pct, + ) + + evaluation = drift_evaluator.evaluate(customer_id, as_of_date) + rebalance_orders.generate_orders(evaluation) + + +_Executor = Callable[["AgentSurfaceUnitOfWork", "AgentActionRequest", uuid.UUID, datetime], None] + +_EXECUTORS: dict[AgentActionType, _Executor] = { + AgentActionType.RESOLVE_BREAK: _execute_resolve_break, + AgentActionType.KYC_OVERRIDE: _execute_kyc_override, + AgentActionType.REBALANCE: _execute_rebalance, +} + + +__all__ = ["agent_requests_bp"] diff --git a/backend/app/controllers/admin/customers.py b/backend/app/controllers/admin/customers.py index 5810d4b..c3279d9 100644 --- a/backend/app/controllers/admin/customers.py +++ b/backend/app/controllers/admin/customers.py @@ -1,12 +1,7 @@ -"""Admin customer directory/detail/fees routes (S8 §4 rows 1, 2, 6). Adviser/admin-only -- a -customer session gets 403, never 404, matching `app/controllers/api/breaks.py`'s -`@requires_role` pattern. - -`GET /admin/customers/` calls the *same* `ValuationService.value_book` code path -`GET /valuation/balance` does, and `GET /admin/customers//fees` calls the *same* -`FeeSummaryService.summarize` `GET /fees` does -- both on `AdminUnitOfWork` -(`app/services/admin/uow.py`), never a second, independently-implemented aggregation that could -report a different figure for the same customer (S8 §6 edge case 4). +"""Admin customer directory/detail/fees routes (S8 §4 rows 1, 2, 6). Adviser/admin-only. + +Reuses `ValuationService.value_book`/`FeeSummaryService.summarize`, never a second +independently-implemented aggregation (S8 §6 edge case 4). """ from __future__ import annotations diff --git a/backend/app/controllers/admin/kyc_overrides.py b/backend/app/controllers/admin/kyc_overrides.py index d2ca7b5..d32b93c 100644 --- a/backend/app/controllers/admin/kyc_overrides.py +++ b/backend/app/controllers/admin/kyc_overrides.py @@ -1,18 +1,5 @@ -"""`POST /api/v1/admin/kyc-overrides/` (S8 §4 row 5, S2 §9's own deferred reopening -gate resolved here). Adviser/admin-only, `@audited` (a privileged action against another -customer's regulatory state). - -**Structural note, matching `app/controllers/api/breaks.py`'s own `@audited` pattern exactly.** -`@audited` needs a `UnitOfWork` among the *decorated function's own* arguments, but this -controller (like every other one) opens `uow` inside a `with` block in the view body -- so the -route opens `uow`, then calls a small inner function (`_apply_override`) taking `uow`/ -`customer_id` as explicit keyword arguments, itself `@audited`-decorated. - -**The reset never touches `kyc_session` rows** (S2 §3.2: that table is append-only, one row per -attempt). Resetting `customer.kyc_status` back to `pending` is the whole fix -- S2 §9's own text -("a new kyc_session row resets attempt_number's effective count"): the very next -`KycService.start_verification` call is no longer blocked by the `kyc_status == rejected` half of -its lock check (`app/services/identity/kyc_service.py`), since that check requires *both* halves. +"""`POST /api/v1/admin/kyc-overrides/` (S8 §4 row 5, S2 §9). Adviser/admin-only, +`@audited`. Resets `customer.kyc_status` to `pending`; never touches `kyc_session` rows (S2 §3.2). """ from __future__ import annotations @@ -77,9 +64,7 @@ def override_kyc_lock(customer_id: uuid.UUID) -> Any: def _apply_override( *, uow: IdentityUnitOfWork, customer_id: uuid.UUID, customer: Customer, reason: str ) -> None: - """A small indirection purely so `@audited` can see `uow`/`customer_id` as this function's - own arguments -- see module docstring. `reason` is captured only in the audit log's payload - hash (via the request body `@audited` already hashes); it has no other effect.""" + """Indirection so `@audited` sees `uow`/`customer_id` as its own arguments.""" customer.kyc_status = KycStatus.pending diff --git a/backend/app/controllers/admin/rebalance.py b/backend/app/controllers/admin/rebalance.py index 673cc3f..e246a3e 100644 --- a/backend/app/controllers/admin/rebalance.py +++ b/backend/app/controllers/admin/rebalance.py @@ -1,10 +1,5 @@ -"""Admin rebalance visibility route (foundation spec `docs/specs/0-backend-foundation-design.md` -§13's routing table: "S9 | `admin/rebalance.py` (visibility only -- rebalance itself is -system-initiated)"). Read-only: shows one customer's current drift status against their assigned -model, computed live via the same `DriftEvaluationService` `MonthlyRebalanceJob` uses -- never -generates an order itself, matching `app/controllers/api/breaks.py`'s `@requires_role` pattern for -an adviser/admin-only route (a customer session gets 403, never 404, per the foundation spec's -general error-response discipline). +"""Admin rebalance visibility route (S9, §13). Read-only: shows a customer's live drift status +against their assigned model via `DriftEvaluationService`; never generates an order itself. """ from __future__ import annotations diff --git a/backend/app/controllers/admin/staff_api_tokens.py b/backend/app/controllers/admin/staff_api_tokens.py new file mode 100644 index 0000000..076edc6 --- /dev/null +++ b/backend/app/controllers/admin/staff_api_tokens.py @@ -0,0 +1,114 @@ +"""Issue/list/revoke the bearer credential an MCP client presents (S13 §3.2, `app/mcp/auth.py`). +Adviser/admin-only, self-service on one's own `staff_id`; issuing is `@audited`. +""" + +from __future__ import annotations + +from datetime import UTC, datetime +from typing import TYPE_CHECKING, Any + +from flask import Blueprint, jsonify, request +from flask_login import current_user +from pydantic import BaseModel, Field +from pydantic import ValidationError as PydanticValidationError + +from app.core.errors import ForbiddenError, NotFoundError, ValidationError +from app.core.security import audited, requires_role +from app.core.uow import SessionRole +from app.extensions import limiter +from app.models.identity.staff_api_token import ( + StaffApiToken, + generate_staff_api_token, + hash_staff_api_token, +) +from app.services.identity.uow import IdentityUnitOfWork +from app.views.staff_api_tokens import ( + StaffApiTokenIssuedResponse, + StaffApiTokensListResponse, + StaffApiTokenSummaryResponse, +) + +if TYPE_CHECKING: + import uuid + +staff_api_tokens_bp = Blueprint( + "admin_staff_api_tokens", __name__, url_prefix="/api/v1/admin/staff-api-tokens" +) + +_STAFF_ROLES = ("adviser", "admin") + + +class _IssueRequest(BaseModel): + label: str = Field(min_length=1) + + +def _to_summary(token: StaffApiToken) -> StaffApiTokenSummaryResponse: + return StaffApiTokenSummaryResponse( + id=token.id, label=token.label, created_at=token.created_at, revoked_at=token.revoked_at + ) + + +@staff_api_tokens_bp.route("", methods=["GET"]) +@limiter.limit("60 per minute") +@requires_role(*_STAFF_ROLES) +def list_tokens() -> Any: + with IdentityUnitOfWork(customer_id=None, role=SessionRole(current_user.role)) as uow: + rows = uow.staff_api_tokens.list_for_staff(current_user.id) + view = StaffApiTokensListResponse(tokens=[_to_summary(row) for row in rows]) + + return jsonify(view.model_dump(mode="json")), 200 + + +@staff_api_tokens_bp.route("", methods=["POST"]) +@limiter.limit("10 per minute") +@requires_role(*_STAFF_ROLES) +def issue_token() -> Any: + try: + body = _IssueRequest.model_validate(request.get_json(silent=True) or {}) + except PydanticValidationError as exc: + raise ValidationError(str(exc)) from exc + + with IdentityUnitOfWork(customer_id=None, role=SessionRole(current_user.role)) as uow: + token, raw_token = _issue_token(uow=uow, staff_id=current_user.id, label=body.label) + uow.commit() + view = StaffApiTokenIssuedResponse( + id=token.id, label=token.label, token=raw_token, created_at=token.created_at + ) + + return jsonify(view.model_dump(mode="json")), 201 + + +@staff_api_tokens_bp.route("/", methods=["DELETE"]) +@limiter.limit("30 per minute") +@requires_role(*_STAFF_ROLES) +def revoke_token(token_id: uuid.UUID) -> Any: + now = datetime.now(UTC) + with IdentityUnitOfWork(customer_id=None, role=SessionRole(current_user.role)) as uow: + token = uow.staff_api_tokens.get_by_id(token_id) + if token is None: + raise NotFoundError(f"staff_api_token {token_id} not found") + if token.staff_id != current_user.id: + raise ForbiddenError("cannot revoke another staff member's API token") + + uow.staff_api_tokens.revoke(token, revoked_at=now) + uow.commit() + view = _to_summary(token) + + return jsonify(view.model_dump(mode="json")), 200 + + +@audited("identity.staff_api_token.issue") +def _issue_token( + *, uow: IdentityUnitOfWork, staff_id: uuid.UUID, label: str +) -> tuple[StaffApiToken, str]: + """Indirection so `@audited` sees `uow` as its own argument; no single-customer target.""" + raw_token = generate_staff_api_token() + token = StaffApiToken( + staff_id=staff_id, label=label, token_hash=hash_staff_api_token(raw_token) + ) + uow.staff_api_tokens.add(token) + uow.session.flush() + return token, raw_token + + +__all__ = ["staff_api_tokens_bp"] diff --git a/backend/app/controllers/api/auth.py b/backend/app/controllers/api/auth.py index bdc9406..64601c0 100644 --- a/backend/app/controllers/api/auth.py +++ b/backend/app/controllers/api/auth.py @@ -1,10 +1,7 @@ -"""Authentication routes (S0 §7.1/§7.2): register, login (customer + staff, one endpoint), -logout, and staff-only MFA enrollment/verification. +"""Authentication routes (S0 §7.1/§7.2): register, login, logout, staff-only MFA enroll/verify. -CSRF: `register` and `login` are exempt — there is no pre-existing authenticated session for -either to protect, and `login`'s response is where a CSRF token is *issued* (S0 §7.1). Every -state-changing route after that (`logout`, `mfa/enroll`, `mfa/verify`) requires the token the -preceding step returned, per `CSRFProtect`'s default enforcement on POST. +`register`/`login` are CSRF-exempt (no session yet to protect); every route after issues/requires +the CSRF token `login` returns. """ from __future__ import annotations @@ -56,11 +53,8 @@ def init_auth(app: Any) -> None: app.config["SESSION_TYPE"] = "redis" - # A dedicated client, deliberately NOT `app.extensions.make_redis()`: that client sets - # `decode_responses=True` (fine for the health check's `PING`), but flask-session's Redis - # backend serializes the session payload to binary (msgpack) and reads it back as bytes — a - # decode-as-UTF-8 client corrupts every read with a `UnicodeDecodeError`, breaking every - # session (login, logout, MFA) the moment its payload isn't valid UTF-8. + # Dedicated client, not app.extensions.make_redis(): that one decodes as UTF-8, which + # corrupts flask-session's binary (msgpack) session payload. app.config["SESSION_REDIS"] = redis.Redis.from_url(app.config["TRUEUP_SETTINGS"].redis_url) app.config["SESSION_USE_SIGNER"] = True app.config["SESSION_COOKIE_HTTPONLY"] = True @@ -75,22 +69,8 @@ def init_auth(app: Any) -> None: @login_manager.user_loader # type: ignore[untyped-decorator] # flask_login ships no py.typed def load_user(user_id: str) -> Any: - # No `current_user` exists yet for this lookup, so it runs as an admin-role session — the - # same defensible exception `register`/`login` already need to resolve an email across every - # customer before authentication exists (S0 §7.3's role-aware RLS policy is what actually - # gates this at the database). - # - # Flask-Login calls this on *every* authenticated request and holds onto the returned object - # as `current_user` well after this `with` block exits. `UnitOfWork.__exit__` calls - # `session.rollback()` on any transaction that never committed (a deliberate "never commit - # implicitly" guarantee, `app/core/uow.py`) -- and `Session.rollback()` expires every - # attribute on every object the session still tracks, so a later read of a real mapped column - # (`current_user.id`, `Staff.role`) raised `DetachedInstanceError`. `session.expunge()` - # detaches the object immediately, before rollback can expire it, so its already-loaded - # attributes stay readable afterward. Detaching here, not inside `find_principal_by_id` - # itself: other callers (e.g. `mfa_enroll`) fetch-then-mutate inside their own `UnitOfWork` - # and depend on the object staying session-tracked for their own `.commit()` to persist the - # write — detaching there silently broke that instead. + # Runs admin-role (no current_user yet). Expunges the object before UnitOfWork's rollback + # expires its attributes, since Flask-Login holds onto it past this `with` block. with IdentityUnitOfWork(customer_id=None, role=SessionRole.ADMIN) as uow: principal = find_principal_by_id(uow, user_id) if principal is not None: @@ -114,19 +94,13 @@ class VerifyRequest(BaseModel): class MfaEnrollRequest(BaseModel): - """`password` is required only for the re-enroll (reset) path -- an already-fully- - authenticated staff session proving they still hold the password before an existing secret - can be replaced (F3 fix). First-time enrollment (no `totp_secret_encrypted` yet, reached only - via `pending_mfa_user_id`, itself only reachable by a correct password at `/login`) needs no - second password check -- there is no existing secret to defeat.""" + """`password` is required only for the re-enroll (reset) path, to re-prove identity (F3 fix).""" password: str | None = None def _regenerate_session() -> None: - """Session-fixation defence (S0 §7.1): a new session ID is issued at the moment a request is - granted a higher privilege level (a full login, or MFA completing a staff login), so a session - ID observed/fixed before authentication cannot be replayed as an authenticated one.""" + """Session-fixation defence (S0 §7.1): new session ID on privilege escalation.""" current_app.session_interface.regenerate(flask_session) # type: ignore[attr-defined] @@ -192,26 +166,17 @@ def login() -> Any: @auth_bp.route("/session", methods=["GET"]) @limiter.limit("60 per minute") def session_info() -> Any: - """`GET /api/v1/auth/session` — session-restore for a page reload or fresh tab. - - The session cookie may still be valid server-side, but a client has no other way to re-derive - who is logged in or obtain a usable CSRF token: both are only ever handed back once, in a - `login`/`mfa/verify` response body (frontend structural spec, `SessionContext`'s mount-time - restore). Returns the same shape `login` does for a fully-authenticated session; `401` for no - session, an anonymous session, or a still-pending-MFA one (that principal is not yet - `login_user()`-ed, exactly like every other check in this module treats it). Read-only (`GET`), - so CSRF-exempt by `CSRFProtect`'s own default, same as every other `GET` in this API. - """ + """Session-restore for a page reload or fresh tab; returns `login`'s shape or 401.""" if not current_user.is_authenticated: raise UnauthenticatedError("No authenticated session") user_id = flask_session.get("_user_id") - if not user_id: # pragma: no cover - defensive; flask-login always sets this once logged in + if not user_id: # pragma: no cover - defensive raise UnauthenticatedError("No authenticated session") with IdentityUnitOfWork(customer_id=None, role=SessionRole.ADMIN) as uow: principal = find_principal_by_id(uow, user_id) - if principal is None: # pragma: no cover - defensive; session named a real prior login + if principal is None: # pragma: no cover - defensive raise UnauthenticatedError("No authenticated session") view = AuthResponse( @@ -235,19 +200,8 @@ def logout() -> Any: @auth_bp.route("/mfa/enroll", methods=["POST"]) @limiter.limit("10 per minute") def mfa_enroll() -> Any: - """F3 fix: a correct password alone must never be enough to (re-)establish the second - factor -- that would make MFA add zero assurance beyond the password it is supposed to - supplement. Two distinct, mutually exclusive paths: - - - **First-time setup**: `pending_mfa_user_id` (set by `/login` on a correct password, before - any TOTP exists for this staff member) is accepted *only* while - `staff.totp_secret_encrypted` is still unset. Once a secret exists, this session state is no - longer sufficient -- it means MFA is already configured and the caller should be calling - `/mfa/verify`, not re-enrolling. - - **Reset**: an already fully-authenticated (post-MFA) staff session may replace an existing - secret, but only after re-proving the password in the request body -- a hijacked session - alone must not be enough to disable and replace the account's second factor. - """ + """F3 fix: first-time setup via `pending_mfa_user_id` (no secret yet), or reset via an + authenticated session that re-proves the password (existing secret being replaced).""" try: data = MfaEnrollRequest.model_validate(request.get_json(silent=True) or {}) except PydanticValidationError as e: diff --git a/backend/app/controllers/api/breaks.py b/backend/app/controllers/api/breaks.py index a92d6b2..59cd0e0 100644 --- a/backend/app/controllers/api/breaks.py +++ b/backend/app/controllers/api/breaks.py @@ -1,22 +1,6 @@ """Admin reconciliation-break routes (S7 §8): list open breaks (aging-sorted, S7 §7) and resolve -one. Adviser/admin-only — a customer session gets 403, not 404 (`@requires_role` raises -`ForbiddenError` for an authenticated non-staff session), matching the foundation spec's general -error-response discipline (S7 §11). - -**`@audited` restructuring, not a decorator change.** `@audited` (`app/core/security.py`) needs a -`UnitOfWork` among the *decorated function's own* arguments (`kwargs.get("uow")`, or scanned from -`args`) — but every controller in this codebase (`app/controllers/api/valuation.py` included) opens -its `uow` inside a `with` block in the view body, never as a parameter Flask itself passes in. -`resolve()` below is `@audited`'s first real consumer; the fix is structural, not a decorator -change: the route opens `uow`, then calls a small inner function (`_resolve_break`) that takes -`uow`/`customer_id` as explicit keyword arguments and is itself `@audited`-decorated — exactly the -shape that decorator's existing `kwargs.get(...)` lookups already expect. - -**`reconciliation_break.customer_id` is nullable** (S7 §5.2, rare — a malformed file row with no -single-customer attribution). `@audited`/`admin_audit_log.target_customer_id` are now -`None`-tolerant (escalated to `main`, resolved as a small additive schema change rather than a -silent workaround) — resolving a customer-less break is still fully audited, just with no customer -to index that one audit row under. +one. Adviser/admin-only (S7 §11). `reconciliation_break.customer_id` is nullable (S7 §5.2); +`@audited`/`admin_audit_log.target_customer_id` are `None`-tolerant to match. """ from __future__ import annotations @@ -139,8 +123,7 @@ def _resolve_break( resolved_at: datetime, resolution_note: str, ) -> None: - """A small indirection purely so `@audited` can see `uow`/`customer_id` as this function's own - arguments -- see module docstring.""" + """Indirection so `@audited` sees `uow`/`customer_id` as its own arguments.""" _apply_resolution( uow, break_row=break_row, diff --git a/backend/app/controllers/api/chat.py b/backend/app/controllers/api/chat.py index c95fbbd..02a2349 100644 --- a/backend/app/controllers/api/chat.py +++ b/backend/app/controllers/api/chat.py @@ -1,12 +1,8 @@ """Chat routes (S11 §6) — session create/list, SSE message stream, message history. Customer-only -(S11 §2's own non-goal: "Adviser/cross-customer chat access" is out of scope), so every route -rejects a staff session with 403 rather than branching on role the way `funding.py`/`statements.py` -do for their customer-or-staff routes. - -`_current_customer_id` reads `flask.session["_user_id"]` rather than `current_user.id`, matching -`funding.py`'s `_authorize_customer_id` -- see that module's docstring for the foundation bug -(`current_user.id` raises `DetachedInstanceError`) this works around; not this sub-project's file -to fix. +(S11 §2), so every route rejects a staff session with 403. + +`_current_customer_id` reads `flask.session["_user_id"]`, not `current_user.id`, to avoid a +`DetachedInstanceError` (see `funding.py`). """ from __future__ import annotations @@ -84,8 +80,6 @@ def _current_customer_id() -> uuid.UUID: def _agent_port() -> LlmAgentPort: settings = get_settings() if not settings.has_openai_credentials: - # Never a silent fallback to a fake in a real deployment -- but a fake keeps this route - # exercisable in an environment with no OpenAI credentials configured yet. if settings.is_production: raise RuntimeError("OPENAI_API_KEY is required in production") return FakeAgentAdapter() @@ -119,8 +113,7 @@ def uow_factory() -> ChatUnitOfWork: def _get_owned_session(customer_id: uuid.UUID, session_id: uuid.UUID) -> ChatSession: with ChatUnitOfWork(customer_id=customer_id, role=SessionRole.CUSTOMER) as uow: session = uow.chat_sessions.get_by_id(session_id) - # RLS already makes another customer's session invisible (S0 §7.3); this is `None` either - # way a caller cannot distinguish "not yours" from "doesn't exist" -- and must not. + # RLS already makes another customer's session invisible (S0 §7.3). if session is None: raise NotFoundError("chat session not found") return session diff --git a/backend/app/controllers/api/fees.py b/backend/app/controllers/api/fees.py index db137df..695c65b 100644 --- a/backend/app/controllers/api/fees.py +++ b/backend/app/controllers/api/fees.py @@ -1,8 +1,5 @@ -"""Fee routes (S10 §7): `GET /api/v1/fees`, `POST /api/v1/payment-methods`. Both routes require an -authenticated principal owning (or a staff member authorized for) the named `customer_id`, matching -`identity.py`/`funding.py`'s established `_authorize_customer_id` pattern (`current_user.id` is -never read directly -- see those modules' own docstrings for the `DetachedInstanceError` this -works around). +"""Fee routes (S10 §7): `GET /api/v1/fees`, `POST /api/v1/payment-methods`. Requires an +authenticated principal owning (or staff authorized for) the named `customer_id`. """ from __future__ import annotations diff --git a/backend/app/controllers/api/funding.py b/backend/app/controllers/api/funding.py index af6f5d0..1b3bfd9 100644 --- a/backend/app/controllers/api/funding.py +++ b/backend/app/controllers/api/funding.py @@ -1,23 +1,7 @@ -"""Funding routes (S2 §6): link a bank account, deposit, withdraw. All four customer routes in -this spec require an authenticated principal owning (or authorized staff for) the named -`customer_id`. - -**`current_user.id` is never read directly** -- a foundation bug (escalated to `main`, not this -sub-project's file to fix; `app/controllers/api/valuation.py`'s `_resolve_customer_id` documents -it first): `load_user()` (`app/controllers/api/auth.py`) returns its principal from inside a -`UnitOfWork` that is never committed, so `UnitOfWork.__exit__` rolls back before closing -- -rollback expires every loaded attribute, and the subsequent close detaches the instance, so any -later access to a *mapped* attribute (`current_user.id`) raises `DetachedInstanceError` on -literally every authenticated request. This is also why `@requires_ownership` -(`app/core/security.py`) is not used here -- it reads `current_user.id` directly. -`_authorize_customer_id` below reads the same value flask-login itself already stored in the -session cookie at login time instead, matching `valuation.py`'s own workaround. - -`POST /deposits`/`POST /withdrawals` require an `Idempotency-Key` header (S0 §8, NFR-14): the key, -the SHA-256 of the exact request body, and the resulting response are stored in the same -`FundingUnitOfWork` transaction as the operation they guard (`.idempotency_keys`, -`app/services/identity/funding_uow.py`), so a replayed request returns the original response -without posting a second journal entry, and a reused key with a changed body is rejected with 409. +"""Funding routes (S2 §6): link a bank account, deposit, withdraw. Requires an authenticated +principal owning (or authorized staff for) the named `customer_id`; `current_user.id` is never +read directly (`DetachedInstanceError`, see `valuation.py`). Deposits/withdrawals require an +`Idempotency-Key` header (S0 §8, NFR-14). """ from __future__ import annotations @@ -82,8 +66,7 @@ class WithdrawalRequest(BaseModel): def _authorize_customer_id(target_customer_id: uuid.UUID) -> None: - """`@login_required` + `@requires_ownership('customer_id')`'s effect, without the - `current_user.id` access that decorator makes (see module docstring).""" + """`@login_required` + `@requires_ownership`'s effect, without reading `current_user.id`.""" if not current_user.is_authenticated: raise UnauthenticatedError("Authentication required") if current_user.role == "customer": @@ -95,8 +78,7 @@ def _authorize_customer_id(target_customer_id: uuid.UUID) -> None: def _resolve_customer_id_for_get(raw_query_customer_id: str | None) -> uuid.UUID: - """A `customer` session always asks about its own bank link; staff must name whose (matching - `valuation.py`'s `_resolve_customer_id` for the same GET-with-optional-`customer_id` shape).""" + """A `customer` session asks about its own bank link; staff must name whose.""" if not current_user.is_authenticated: raise UnauthenticatedError("Authentication required") if current_user.role == "customer": @@ -157,11 +139,7 @@ def _save_idempotency_record( @funding_bp.route("/link-token", methods=["POST"]) @limiter.limit("10 per minute") def create_link_token() -> Any: - """`POST /api/v1/funding/link-token` — mints the `link_token` Plaid Link's client SDK needs to - open at all (frontend structural spec's onboarding wizard). A precursor step to `POST - /bank-links`: nothing is persisted here, so no `UnitOfWork` is opened — a pure passthrough to - the provider, the same shape `start_kyc_session` (`identity.py`) already establishes for a - provider call with no local state of its own.""" + """Mints the `link_token` Plaid Link's client SDK needs; a pure passthrough, no local state.""" try: data = LinkTokenRequest.model_validate(request.get_json(silent=True) or {}) except PydanticValidationError as exc: @@ -176,11 +154,7 @@ def create_link_token() -> Any: @funding_bp.route("/cash-summary", methods=["GET"]) @limiter.limit("60 per minute") def get_cash_summary() -> Any: - """`GET /api/v1/funding/cash-summary` -- withdrawable vs. investable cash (frontend - escalation: `structure.md`'s `CashSummary` component and `useCashPolicy` hook had no endpoint - to call; `design-system.md` §8.2 requires both figures shown as equal-weight, never merged). - Uses the same real `OrderHoldsProvider` the withdrawal endpoint validates against, so this - figure and the enforcement behind `insufficient_withdrawable_cash` can never disagree.""" + """Withdrawable vs. investable cash, via the same `OrderHoldsProvider` withdrawal validates.""" customer_id = _resolve_customer_id_for_get(request.args.get("customer_id")) role, uow_customer_id = _session_role_and_customer_id(customer_id) @@ -197,10 +171,7 @@ def get_cash_summary() -> Any: @funding_bp.route("/bank-links/current", methods=["GET"]) @limiter.limit("30 per minute") def get_current_bank_link() -> Any: - """`GET /api/v1/funding/bank-links/current` -- "is a bank already linked, and is it usable" - (frontend escalation: onboarding and the funding screen both need this and had no way to ask - it). `None` `bank_link` means never linked; `status` distinguishes `active` from - `requires_reauth` for a link that exists but currently can't fund a deposit/withdrawal.""" + """Is a bank linked, and usable. `None` means never linked; `status` covers reauth needs.""" customer_id = _resolve_customer_id_for_get(request.args.get("customer_id")) role, uow_customer_id = _session_role_and_customer_id(customer_id) diff --git a/backend/app/controllers/api/identity.py b/backend/app/controllers/api/identity.py index b6ea978..420f771 100644 --- a/backend/app/controllers/api/identity.py +++ b/backend/app/controllers/api/identity.py @@ -1,19 +1,7 @@ """Identity routes (S2 §6): start a Stripe Identity verification session, read both approval -gates. Both routes require an authenticated principal owning (or a staff member authorized for) -the named `customer_id`. - -**`current_user.id` is never read directly** -- a foundation bug (escalated to `main`, not this -sub-project's file to fix; `app/controllers/api/valuation.py`'s `_resolve_customer_id` documents -it first): `load_user()` (`app/controllers/api/auth.py`) returns its principal from inside a -`UnitOfWork` that is never committed, so `UnitOfWork.__exit__` rolls back before closing -- -rollback expires every loaded attribute, and the subsequent close detaches the instance, so any -later access to a *mapped* attribute (`current_user.id`, `Staff.role`, though not `Customer.role`, -a plain Python property) raises `DetachedInstanceError` on literally every authenticated request. -This is also why `@requires_ownership` (`app/core/security.py`) is not used here -- it reads -`current_user.id` directly. `_authorize_customer_id` below reads the same value flask-login itself -already stored in the session cookie at login time instead, matching `valuation.py`'s own -`_resolve_customer_id` workaround, applied to a POST body's `customer_id` instead of a query -parameter. +gates. Requires an authenticated principal owning (or staff authorized for) the named +`customer_id`; `current_user.id` is never read directly (`DetachedInstanceError`, see +`valuation.py`). """ from __future__ import annotations @@ -32,6 +20,8 @@ from app.core.uow import SessionRole from app.extensions import DbRole, limiter from app.integrations.stripe.kyc_adapter import StripeKycAdapter +from app.models.identity.customer import KycStatus +from app.services.identity.account_approval_service import AccountApprovalService from app.services.identity.funding_uow import FundingUnitOfWork from app.services.identity.kyc_service import KycLockedError, KycService from app.views.identity import IdentityConfigResponse, IdentityStatusResponse, KycSessionResponse @@ -47,11 +37,7 @@ class StartKycSessionRequest(BaseModel): def _build_kyc_port() -> KycPort: - """The live `KycPort`, built here rather than inline so `tests/api/` can substitute a real - fake (`FakeKycAdapter`, structurally identical to `StripeKycAdapter`) via monkeypatch, without - the request handler ever branching on "are we under test" -- this endpoint's whole contract is - a synchronous provider call (S2 §6: the response must carry Stripe's real `client_secret`), so - there is no async seam to defer it through, unlike order submission (ADR 7).""" + """The live `KycPort`, built here so tests can substitute a fake via monkeypatch.""" settings = get_settings() if settings.stripe_secret_key is None: raise RuntimeError("STRIPE_SECRET_KEY is not configured") @@ -59,8 +45,7 @@ def _build_kyc_port() -> KycPort: def _authorize_customer_id(target_customer_id: uuid.UUID) -> None: - """`@login_required` + `@requires_ownership('customer_id')`'s effect, without the - `current_user.id` access that decorator makes (see module docstring).""" + """`@login_required` + `@requires_ownership`'s effect, without reading `current_user.id`.""" if not current_user.is_authenticated: raise UnauthenticatedError("Authentication required") if current_user.role == "customer": @@ -84,9 +69,7 @@ def _session_role_and_customer_id( @identity_bp.route("/config", methods=["GET"]) @limiter.limit("30 per minute") def get_identity_config() -> Any: - """`GET /api/v1/identity/config` -- the Stripe publishable key the onboarding wizard's - Stripe.js `verifyIdentity(client_secret)` call needs client-side (frontend structural spec). - Any authenticated principal; not customer-scoped data, so no ownership check applies.""" + """The Stripe publishable key for client-side use; not customer-scoped, no ownership check.""" if not current_user.is_authenticated: raise UnauthenticatedError("Authentication required") @@ -129,16 +112,31 @@ def start_kyc_session() -> Any: @identity_bp.route("/status/", methods=["GET"]) @limiter.limit("30 per minute") def get_identity_status(customer_id: uuid.UUID) -> Any: + """Self-healing: when `kyc_status` is still `pending`, polls the provider directly for the + latest verification session's live status before answering, rather than only trusting a + verdict webhook to have arrived -- a webhook can be delayed, dropped, or (in local dev) + entirely unreachable.""" _authorize_customer_id(customer_id) role, uow_customer_id = _session_role_and_customer_id(customer_id) + settings = get_settings() with FundingUnitOfWork(customer_id=uow_customer_id, role=role, db_role=DbRole.APP) as uow: customer = uow.customers.get_by_id(customer_id) if customer is None: raise ValidationError("customer not found") + + if customer.kyc_status is KycStatus.pending and settings.stripe_secret_key is not None: + service = KycService( + uow, kyc_port=_build_kyc_port(), max_attempts=settings.kyc_max_attempts + ) + verified_customer_id = service.sync_latest_verification(customer_id) + if verified_customer_id is not None: + AccountApprovalService(uow).approve_if_eligible(verified_customer_id) + view = IdentityStatusResponse( kyc_status=customer.kyc_status.value, account_approval_status=customer.account_approval_status.value, ) + uow.commit() return jsonify(view.model_dump(mode="json")), 200 diff --git a/backend/app/controllers/api/lots.py b/backend/app/controllers/api/lots.py index 5cc356d..81fa7a5 100644 --- a/backend/app/controllers/api/lots.py +++ b/backend/app/controllers/api/lots.py @@ -1,17 +1,8 @@ """Tax lot routes (S8 §3, data owned by S5) -- `GET /api/v1/lots`: quantity, cost basis (original -and wash-sale-adjusted), realized gains, and provisional flags for every lot a customer has ever -opened. - -Every route is authenticated and tenant-scoped (root `CLAUDE.md`'s non-negotiable), following -`app/controllers/api/statements.py`'s exact pattern: a `customer` session only ever sees its own -lots; `adviser`/`admin` pass `customer_id` explicitly, gated by `@requires_role` plus RLS's -role-aware policy underneath (ADR 17). - -**Never the raw pre-adjustment basis/gain.** `TaxLot.adjusted_basis` and -`LotConsumption.realized_gain_loss` are S5's own mutate-in-place fields -- by the time a wash sale -(S5 §5) has been applied, both already carry the adjusted figure, so this module only ever reads -those two columns and never `original_cost_basis` for anything but the immutable "as originally -purchased" reference figure (S5 §7 edge case 1's own warning, restated in S8 §3's route table). +and wash-sale-adjusted), realized gains, and provisional flags for every lot. + +Reads `adjusted_basis`/`realized_gain_loss` (already wash-sale-adjusted, S5 §5); never +`original_cost_basis` except as the immutable "as purchased" reference (S5 §7 edge case 1). """ from __future__ import annotations @@ -38,9 +29,7 @@ def _resolve_customer_id() -> uuid.UUID: - """A `customer` session always sees its own data; staff must name whose (FR-31). See - `app/controllers/api/valuation.py::_resolve_customer_id`'s own docstring for why this reads - `flask.session["_user_id"]` rather than `current_user.id`.""" + """A `customer` session sees its own data; staff must name whose (FR-31).""" if current_user.role == "customer": raw_user_id = flask_session.get("_user_id") if not raw_user_id: @@ -60,8 +49,7 @@ def _session_role() -> SessionRole: def _uow_customer_id(customer_id: uuid.UUID) -> uuid.UUID | None: - """`UnitOfWork` requires `customer_id=None` for an adviser/admin session (RLS's role branch, - not `customer_id`, is what admits their reads — `app/core/uow.py`).""" + """`UnitOfWork` requires `customer_id=None` for an adviser/admin session (RLS admits reads).""" return customer_id if _session_role() is SessionRole.CUSTOMER else None diff --git a/backend/app/controllers/api/orders.py b/backend/app/controllers/api/orders.py index 9d990ad..a871791 100644 --- a/backend/app/controllers/api/orders.py +++ b/backend/app/controllers/api/orders.py @@ -1,30 +1,9 @@ -"""Order routes (S3 §6): create, approve, and read — the three customer-facing routes this spec -defines. Broker events reach the system over the `trade_updates` websocket (ADR 22), not a -webhook controller here. - -Every route is authenticated and tenant-scoped (root `CLAUDE.md`): a `customer` session only ever -acts on its own orders; `adviser`/`admin` may pass `customer_id` explicitly for cross-customer -reads, matching `app/controllers/api/valuation.py`'s own `_resolve_customer_id` pattern (small -enough, and specific enough to each controller's routes, that it is duplicated rather than shared -cross-module — the same choice that controller already made). - -`POST /orders` accepts `reference_price` in the request body -- see -`app.services.orders.order_service`'s module docstring for why: `order`'s schema has no price -field, and this sub-project's own escalation on the point is still open as of this writing. -`symbol` is no longer part of either this route's or `POST /orders//approve`'s request body -- -`OrderService.enqueue_submission` resolves it from S5's securities catalogue instead (a caller -having to already know and resupply a symbol its own approve action was never given was a real, -unnecessary gap, frontend escalation). `OrderResponse.symbol` is resolved the same way, for -display. - -**`current_user.id` is never read directly** -- a foundation bug (escalated to `main`, not this -sub-project's file to fix; `app/controllers/api/valuation.py`'s `_resolve_customer_id` documents -it in full): `load_user()` (`app/controllers/api/auth.py`) returns its principal from inside a -`UnitOfWork` that is never committed, so `UnitOfWork.__exit__` rolls back before closing -- -rollback expires every loaded attribute, and the close then detaches the instance, so any later -access to a *mapped* attribute (`current_user.id`, `current_user.get_id()`) raises -`DetachedInstanceError` on literally every authenticated request. `_resolve_customer_id` below -reads the same value flask-login already stored in the session cookie at login time instead. +"""Order routes (S3 §6): create, approve, and read. Broker events reach the system over the +`trade_updates` websocket (ADR 22), not a webhook controller here. + +`POST /orders` accepts `reference_price` (order's schema has no price field). `symbol` is resolved +from S5's securities catalogue, not the request body. `current_user.id` is never read directly +(`DetachedInstanceError`, see `valuation.py`). """ from __future__ import annotations @@ -92,9 +71,7 @@ class CreateOrderRequest(BaseModel): def _resolve_customer_id() -> uuid.UUID: - """A `customer` session always acts on its own data; staff must name whose (FR-31's shape, - reused here for the identical reason `valuation.py` already states it). See module docstring - for why this reads `flask.session["_user_id"]` rather than `current_user.id`.""" + """A `customer` session acts on its own data; staff must name whose (FR-31).""" if current_user.role == "customer": raw_user_id = flask_session.get("_user_id") if not raw_user_id: @@ -127,11 +104,7 @@ def _order_service(uow: OrdersUnitOfWork) -> OrderService: def _to_order_response(uow: OrdersUnitOfWork, order: Order) -> OrderResponse: - """`OrderResponse.symbol` comes from S5's securities catalogue, not `order` itself (which has - no `symbol` column, only `security_id`) -- resolved the same way - `OrderService.enqueue_submission` now does, so display and broker-submission never disagree. - Built field-by-field rather than `OrderResponse.model_validate(order)` because `order` itself - has no `symbol` attribute for `from_attributes` validation to find.""" + """`symbol` is resolved from S5's securities catalogue; `order` has no `symbol` column.""" security = uow.securities.get_by_id(order.security_id) symbol = security.symbol if security is not None else "" return OrderResponse( @@ -221,10 +194,7 @@ def approve_order(order_id: uuid.UUID) -> Any: customer_id = _resolve_customer_id() with OrdersUnitOfWork(customer_id=customer_id, role=SessionRole.CUSTOMER) as uow: - # Tenant-scoped `get_for_update` (RLS plus `BaseRepository`'s application-layer filter) - # is the ownership check here: an order belonging to another customer is invisible to - # this query, not merely forbidden -- matching OWASP's guidance against confirming another - # customer's resource even exists. + # Tenant-scoped get_for_update is the ownership check: another's order is invisible. try: service = _order_service(uow) order = service.approve(order_id) diff --git a/backend/app/controllers/api/portfolios.py b/backend/app/controllers/api/portfolios.py index 0b56f1a..66e064e 100644 --- a/backend/app/controllers/api/portfolios.py +++ b/backend/app/controllers/api/portfolios.py @@ -1,19 +1,7 @@ -"""Portfolio-model routes (S8 §3, attributed there to "Owning spec: S9 §3" -- see -`DECISION-LOG.md`'s "S9 build includes `/portfolios/models` and `/portfolios/assignment`" entry): -list the four model portfolios' public descriptions, and view/select a customer's assignment -(FR-7). S8 gives only method + one-line purpose, no field-level schema -- the request/response -shapes below are this wave's own design, following this codebase's existing view/schema -conventions (`app/views/portfolios.py`) and `app/controllers/api/orders.py`/`valuation.py`'s -controller patterns. - -`assigned_at` is anchored to `MarketClock` (America/New_York, ADR 12/NFR-13), not a bare -server-local date -- the same date-boundary discipline every other day-stamped write in this -codebase already follows. - -Unlike several older controllers in this codebase, `current_user.id`/`current_user.role` are read -directly here: the `DetachedInstanceError` bug that once made that unsafe was fixed at its actual -source (`load_user()`'s `session.expunge()`, `app/controllers/api/auth.py`) before this file was -written, so there is no workaround left to copy forward into a new file. +"""Portfolio-model routes (S8 §3, owning spec S9 §3): list the four model portfolios and +view/select a customer's assignment (FR-7). `assigned_at` is anchored to `MarketClock` +(America/New_York, ADR 12/NFR-13). `current_user.id`/`.role` are read directly here since the +`DetachedInstanceError` bug was fixed before this file was written. """ from __future__ import annotations @@ -54,10 +42,7 @@ class AssignModelRequest(BaseModel): def _resolve_customer_id() -> uuid.UUID: - """A `customer` session always sees its own assignment; staff must name whose (matching - `valuation.py`'s `_resolve_customer_id` for the identical GET-with-optional-`customer_id` - shape, minus that file's now-unnecessary `flask.session` workaround -- see module - docstring).""" + """A `customer` session sees its own assignment; staff must name whose.""" if current_user.role == "customer": return cast("uuid.UUID", current_user.id) raw = request.args.get("customer_id") @@ -70,11 +55,7 @@ def _resolve_customer_id() -> uuid.UUID: def _authorize_customer_id(target_customer_id: uuid.UUID) -> None: - """`@login_required` + `@requires_ownership('customer_id')`'s effect. Not `@requires_ownership` - itself: that decorator only reads a `customer_id` from the route's own kwargs, its JSON body, - or its form body -- never a query string -- so it does not fit `get_assignment`'s staff-via- - `?customer_id=` shape, and this file uses one helper for both routes rather than mixing the - real decorator into only one of them.""" + """`@login_required` + `@requires_ownership`'s effect; also covers `customer_id` via query.""" if not current_user.is_authenticated: raise UnauthenticatedError("Authentication required") if current_user.role == "customer": diff --git a/backend/app/controllers/api/statements.py b/backend/app/controllers/api/statements.py index 71c44ef..202c9ca 100644 --- a/backend/app/controllers/api/statements.py +++ b/backend/app/controllers/api/statements.py @@ -1,9 +1,6 @@ """Statements routes (S6 §8, FR-25/26) — the as-published figures S8/S11 both read identically. - -Every route is authenticated and tenant-scoped (root `CLAUDE.md`'s non-negotiable), following -`app/controllers/api/valuation.py`'s exact pattern: a `customer` session only ever sees its own -data; `adviser`/`admin` pass `customer_id` explicitly (FR-31), gated by `@requires_role` plus RLS's -role-aware policy underneath (ADR 17). +A `customer` session sees only its own data; `adviser`/`admin` pass `customer_id` explicitly +(FR-31, ADR 17). """ from __future__ import annotations @@ -35,9 +32,7 @@ def _resolve_customer_id() -> uuid.UUID: - """A `customer` session always sees its own data; staff must name whose (FR-31). See - `app/controllers/api/valuation.py::_resolve_customer_id`'s own docstring for why this reads - `flask.session["_user_id"]` rather than `current_user.id`.""" + """A `customer` session sees its own data; staff must name whose (FR-31).""" if current_user.role == "customer": raw_user_id = flask_session.get("_user_id") if not raw_user_id: @@ -57,8 +52,7 @@ def _session_role() -> SessionRole: def _uow_customer_id(customer_id: uuid.UUID) -> uuid.UUID | None: - """`UnitOfWork` requires `customer_id=None` for an adviser/admin session (RLS's role branch, - not `customer_id`, is what admits their reads — `app/core/uow.py`).""" + """`UnitOfWork` requires `customer_id=None` for an adviser/admin session (RLS admits reads).""" return customer_id if _session_role() is SessionRole.CUSTOMER else None @@ -145,10 +139,7 @@ def get_statement(period_start: str) -> Any: @limiter.limit("30 per minute") @requires_role("customer", *_STAFF_ROLES) def export_statement(period_start: str) -> Any: - """`GET /api/v1/statements//export` (S8 §5, FR-36) -- a CSV of every lot consumption - realized within the as-published period, never the raw pre-wash-sale-adjustment figure (S5's - own explicit warning, S8 §3's route table). A period never published returns a clear - "not yet published" `404` rather than falling back to a live-derived export (S8 §6 case 1).""" + """CSV of realized lot consumptions for the published period (S8 §5, FR-36); else 404.""" customer_id = _resolve_customer_id() try: parsed_period_start = date.fromisoformat(period_start) diff --git a/backend/app/controllers/api/valuation.py b/backend/app/controllers/api/valuation.py index 3dbda0d..6223f9b 100644 --- a/backend/app/controllers/api/valuation.py +++ b/backend/app/controllers/api/valuation.py @@ -1,9 +1,5 @@ -"""Valuation & returns routes (S4 §7): balance, returns, and history (FR-18). - -Every route is authenticated and tenant-scoped (root `CLAUDE.md`'s non-negotiable): a `customer` -session can only ever see its own data; `adviser`/`admin` may pass `customer_id` explicitly for -FR-31's cross-customer reconciliation view, gated by `@requires_role` plus RLS's role-aware policy -underneath (ADR 17) — the same defense-in-depth `BaseRepository`'s own docstring describes. +"""Valuation & returns routes (S4 §7): balance, returns, and history (FR-18). A `customer` session +sees only its own data; `adviser`/`admin` may pass `customer_id` explicitly (FR-31, ADR 17). """ from __future__ import annotations @@ -47,18 +43,11 @@ class _ReturnsQuery(BaseModel): def _resolve_customer_id() -> uuid.UUID: - """A `customer` session always sees its own data; staff must name whose (FR-31). - - Reads the id from `flask.session["_user_id"]` (flask-login's own cookie key) rather than - `current_user.id` -- a foundation bug (escalated to `main`, not this sub-project's file to - fix): `load_user()` (`app/controllers/api/auth.py`) returns its principal from inside a - `UnitOfWork` that is never committed, so `UnitOfWork.__exit__` rolls back before closing -- - rollback expires every loaded attribute, and the subsequent close detaches the instance, so - any later access to a *mapped* attribute (`current_user.id`, `current_user.get_id()`, and - `Staff.role`, though not `Customer.role`, which is a plain Python property) raises - `DetachedInstanceError` on literally every authenticated request. This reads the same value - flask-login itself already stored in the session cookie at login time, sidestepping the - detached instance without touching `current_user`, `app/core/uow.py`, or `app/core/security.py`. + """A `customer` session sees its own data; staff must name whose (FR-31). + + Reads `flask.session["_user_id"]` rather than `current_user.id`, which raises + `DetachedInstanceError` on every authenticated request (`load_user()`'s uncommitted UnitOfWork + expires and detaches the principal on exit -- a foundation bug, not fixed here). """ if current_user.role == "customer": raw_user_id = flask_session.get("_user_id") @@ -79,8 +68,7 @@ def _session_role() -> SessionRole: def _uow_customer_id(customer_id: uuid.UUID) -> uuid.UUID | None: - """`UnitOfWork` requires `customer_id=None` for an adviser/admin session (RLS's role branch, - not `customer_id`, is what admits their reads — `app/core/uow.py`).""" + """`UnitOfWork` requires `customer_id=None` for an adviser/admin session (RLS admits reads).""" return customer_id if _session_role() is SessionRole.CUSTOMER else None diff --git a/backend/app/controllers/health/__init__.py b/backend/app/controllers/health/__init__.py index 7020a7e..b843c46 100644 --- a/backend/app/controllers/health/__init__.py +++ b/backend/app/controllers/health/__init__.py @@ -17,23 +17,13 @@ @health_bp.get("/live") def live() -> dict[str, str]: - """Is this process running? - - Deliberately touches nothing external. A liveness probe that checks the database restarts a - perfectly healthy container whenever the database blips, turning a brief dependency outage - into a restart storm. - """ + """Is this process running? Touches nothing external.""" return {"status": "alive"} @health_bp.get("/ready") def ready() -> tuple[dict[str, Any], int]: - """Can this process serve traffic? - - Reports each dependency as a plain boolean. Never the exception text, hostname, port, or - driver name: this endpoint is unauthenticated, and those details map the internal topology - for anyone who asks. - """ + """Can this process serve traffic? Reports each dependency as a plain boolean, no internals.""" checks = {"database": _database_reachable(), "redis": _redis_reachable()} ok = all(checks.values()) return {"status": "ready" if ok else "not_ready", "checks": checks}, 200 if ok else 503 diff --git a/backend/app/controllers/webhooks/plaid.py b/backend/app/controllers/webhooks/plaid.py index 94cd538..f09d4e0 100644 --- a/backend/app/controllers/webhooks/plaid.py +++ b/backend/app/controllers/webhooks/plaid.py @@ -1,8 +1,5 @@ -"""`POST /webhooks/plaid` (S2 §5.2 step 4/§5.4, FR-6/FR-43) -- Plaid `ITEM`/`TRANSFER` events, -through the foundation spec's one shared intake path (`EventIntakeService`). No bespoke webhook -mechanism: this controller only verifies the signature, hands the envelope to intake for dedup + -durable recording, and -- once intake accepts it -- applies the effect via `BankLinkService` -(`ITEM_LOGIN_REQUIRED`, FR-43) or `DepositService` (a bounced ACH return, FR-6). +"""`POST /webhooks/plaid` (S2 §5.2 step 4/§5.4, FR-6/FR-43) -- Plaid `ITEM`/`TRANSFER` events via +`EventIntakeService`, then applies the effect through `BankLinkService`/`DepositService`. """ from __future__ import annotations @@ -37,12 +34,7 @@ class PlaidWebhookPayload(BaseModel): - """S0 §6: every provider payload is parsed through a Pydantic model before any service sees - it -- provider data is untrusted input (OWASP API10). - - Dedupe key per S0 §6: "Plaid: the webhook's own event identity plus `item_id`" -- modeled here - as `webhook_code` + `item_id`, since sandbox Plaid webhooks carry no separate event ID field. - """ + """Validated provider payload (S0 §6, OWASP API10). Dedupe key: `webhook_code` + `item_id`.""" webhook_type: str webhook_code: str @@ -105,8 +97,7 @@ def _apply_effect(parsed: PlaidWebhookPayload) -> None: def _apply_item_login_required(plaid_item_id: str) -> None: - """FR-43. An unmatched `item_id` is logged and ignored rather than raised -- the webhook has - already been durably recorded by intake, and Plaid must not see anything but 200.""" + """FR-43. An unmatched `item_id` is ignored, not raised -- Plaid must see only 200.""" with _funding_uow() as uow: with suppress(BankLinkNotFoundError): BankLinkService(uow).apply_item_login_required(plaid_item_id) diff --git a/backend/app/controllers/webhooks/stripe_billing.py b/backend/app/controllers/webhooks/stripe_billing.py index 0aed104..b468729 100644 --- a/backend/app/controllers/webhooks/stripe_billing.py +++ b/backend/app/controllers/webhooks/stripe_billing.py @@ -1,12 +1,5 @@ -"""`POST /webhooks/stripe_billing` (S10 §7, ADR 10) — Stripe Billing `payment_intent.*` events, -through the foundation spec's one shared intake path (`EventIntakeService`), deduped on the -Stripe *event* id (`evt_...`) -- never the PaymentIntent id (this system's `stripe_charge_id`), -which is stable across a PaymentIntent's whole lifecycle and would make every event after the -first for one intent a false "duplicate" (F4 fix). Mirrors `stripe_identity.py`'s exact shape: -this controller only verifies the signature and hands the envelope to intake for dedupe + durable -recording; once intake accepts a recognized `payment_intent.*` event, the verdict is applied via -`FeeChargeService`, idempotently (a webhook confirming what the outbox handler's own synchronous -call already applied is a no-op, per `PaymentPort`'s own docstring). +"""`POST /webhooks/stripe_billing` (S10 §7, ADR 10) — Stripe Billing `payment_intent.*` events via +`EventIntakeService`, deduped on the Stripe event id, never the PaymentIntent id (F4 fix). """ from __future__ import annotations @@ -52,8 +45,7 @@ class _StripeEventData(BaseModel): class StripeBillingWebhookPayload(BaseModel): - """S0 §6: every provider payload is parsed through a Pydantic model before any service sees - it -- provider data is untrusted input (OWASP API10).""" + """Validated provider payload (S0 §6, OWASP API10).""" id: str type: str @@ -87,12 +79,7 @@ def stripe_billing_webhook() -> Any: event = IncomingEvent( source=InboundEventSource.STRIPE, - # F4 fix: dedupe on the Stripe *event* id (`evt_...`), never the PaymentIntent id. The - # PaymentIntent id is stable across its entire lifecycle (`processing` then later - # `succeeded` share one), so keying on it made every event after the first for a given - # intent a permanent, silently-dropped "duplicate" -- the fee_charge was then never marked - # paid, and no retry could recover it (non-negotiable #2: "out-of-order delivery - # tolerated"). The PaymentIntent id still travels in the payload for correlation. + # F4 fix: dedupe on the Stripe event id, not the PaymentIntent id (stable across lifecycle). source_event_id=parsed.id, payload=parsed.model_dump(mode="json"), ) @@ -110,10 +97,7 @@ def _apply_verdict(*, stripe_charge_id: str, status: str) -> None: with _fees_uow() as uow: charge = uow.fee_charges.get_by_stripe_charge_id(stripe_charge_id) if charge is None: - # Either the outbox handler hasn't set stripe_charge_id yet (a benign race -- the - # eventual consistency window between the synchronous PaymentIntent response and this - # webhook), or the event names a charge this system never initiated. Neither is an - # error to surface to Stripe; acknowledge and move on. + # Benign race (outbox hasn't set stripe_charge_id yet) or an unrelated charge. uow.commit() return diff --git a/backend/app/controllers/webhooks/stripe_identity.py b/backend/app/controllers/webhooks/stripe_identity.py index 8716381..ddca4fe 100644 --- a/backend/app/controllers/webhooks/stripe_identity.py +++ b/backend/app/controllers/webhooks/stripe_identity.py @@ -1,8 +1,5 @@ -"""`POST /webhooks/stripe_identity` (S2 §4/§6, ADR 9) -- Stripe Identity verification-session -events, through the foundation spec's one shared intake path (`EventIntakeService`). No bespoke -webhook mechanism: this controller only verifies the signature, hands the envelope to intake for -dedup + durable recording, and -- once intake accepts it -- applies the verdict via `KycService` -and, when it lands the customer on `kyc_status = approved`, checks `AccountApprovalService`. +"""`POST /webhooks/stripe_identity` (S2 §4/§6, ADR 9) -- Stripe Identity events via +`EventIntakeService`, applying the verdict through `KycService`/`AccountApprovalService`. """ from __future__ import annotations @@ -50,8 +47,7 @@ class _StripeEventData(BaseModel): class StripeIdentityWebhookPayload(BaseModel): - """S0 §6: every provider payload is parsed through a Pydantic model before any service sees - it -- provider data is untrusted input (OWASP API10).""" + """Validated provider payload (S0 §6, OWASP API10).""" id: str type: str @@ -89,12 +85,7 @@ def stripe_identity_webhook() -> Any: event = IncomingEvent( source=InboundEventSource.STRIPE, - # F4 fix: dedupe on the Stripe *event* id (`evt_...`), never the verification-session id. - # The session id is stable across a session's entire lifecycle (`requires_input` then - # later `verified` share one), so keying on it made every event after the first for a - # given session a permanent, silently-dropped "duplicate" -- the customer was then never - # approved, and no retry could recover it (non-negotiable #2: "out-of-order delivery - # tolerated"). The session id still travels in the payload for correlation. + # F4 fix: dedupe on the Stripe event id, not the verification-session id (stable lifecycle). source_event_id=parsed.id, payload=parsed.model_dump(mode="json"), ) diff --git a/backend/app/core/clock.py b/backend/app/core/clock.py index 78ad525..f7e9028 100644 --- a/backend/app/core/clock.py +++ b/backend/app/core/clock.py @@ -1,18 +1,4 @@ -"""MarketClock: the only code allowed to convert a UTC instant into a market day (ADR 12, S0 §10.8). - -Every "daily," "morning," and "T+1" concept in the brief (valuation, reconciliation, settlement) is -a US market-day concept, not a server-clock-day concept. New York sits behind UTC, so a stored UTC -instant in the evening is already tomorrow in UTC while still today in New York; code that calls -`.date()` on a UTC instant directly gets that backwards, and the wrongness silently shifts by an -hour every time US daylight saving flips. `MarketClock.market_date()` is the one place that -conversion happens, so no other module can get it wrong independently (ADR 12). - -Layering constraint (S0 §3): `app/core/` imports nothing else under `app/`, so `MarketClock` -cannot read `market_calendar_cache` or import a model. `TradingCalendar` is the seam: a `Protocol` -this module owns, injected at construction. `InMemoryTradingCalendar` (below) is the calendar for -tests and the fake adapter now; the database-backed implementation reading `market_calendar_cache` -arrives in Wave 4 (S4) as another `TradingCalendar`, without this module changing at all. -""" +"""The only code allowed to convert a UTC instant into a market day (ADR 12, S0 §10.8).""" from __future__ import annotations @@ -21,52 +7,31 @@ from zoneinfo import ZoneInfo MARKET_TIMEZONE = ZoneInfo("America/New_York") -"""ADR 12: the single timezone every daily-boundary computation in the system anchors to.""" +"""ADR 12: the timezone every daily-boundary computation anchors to.""" _MAX_CALENDAR_SEARCH_DAYS = 14 -"""Longest real US market closure (year-end plus a holiday) is a handful of days; this is a -generous bound whose only job is turning a misconfigured calendar into a loud error instead of an -infinite loop.""" +"""Bound that turns a misconfigured calendar into a loud error instead of an infinite loop.""" class CalendarExhaustedError(RuntimeError): - """No trading day was found within the bounded search window. - - This means the injected `TradingCalendar` is misconfigured (e.g. every day marked a holiday), - not that the market is closed for an unusually long stretch — a real closure is always far - shorter than `_MAX_CALENDAR_SEARCH_DAYS`. - """ + """No trading day found in the search window — the injected calendar is misconfigured.""" @runtime_checkable class TradingCalendar(Protocol): - """The market-calendar seam `app/core/` depends on without importing a model. - - A database-backed implementation reading `market_calendar_cache` (S4) and - `InMemoryTradingCalendar` (tests, and the fake adapter) both satisfy this without either one - knowing about the other. - """ + """Market-calendar seam `app/core/` depends on without importing a model.""" def is_trading_day(self, d: date) -> bool: """Whether `d` is a US market trading day (not a weekend, not a holiday).""" ... def session_close(self, d: date) -> datetime | None: - """The instant trading ends for `d`, tz-aware in `MARKET_TIMEZONE`. - - `None` if `d` is not a trading day. A half day returns its real early-close instant, never - an assumed 4pm (S0 §10.8). - """ + """Instant trading ends for `d`, tz-aware; `None` if `d` is not a trading day.""" ... class InMemoryTradingCalendar: - """A `TradingCalendar` defined by an explicit holiday and half-day set. - - A trading day is any weekday not listed in `holidays`. `half_days` maps a date to its close - time in `MARKET_TIMEZONE` (e.g. 1pm on the day after Thanksgiving); every other trading day - closes at 4pm. - """ + """A `TradingCalendar` defined by an explicit holiday and half-day set.""" def __init__( self, @@ -88,22 +53,13 @@ def session_close(self, d: date) -> datetime | None: class MarketClock: - """Converts a UTC instant into "which market day is this" — S0 §10.8's one allowed seam. - - Constructor-injected with a `TradingCalendar` so this class never depends on how the calendar - is sourced (in-memory fixture today, `market_calendar_cache` from S4 later). - """ + """Converts a UTC instant into "which market day is this" — S0 §10.8's one allowed seam.""" def __init__(self, calendar: TradingCalendar) -> None: self._calendar = calendar def market_date(self, instant: datetime) -> date: - """The America/New_York calendar date `instant` falls on. - - Rejects a naive `instant` rather than assuming a timezone: a naive datetime silently - assumes the server's local zone, which is exactly the off-by-one-day bug ADR 12 exists to - prevent. - """ + """The America/New_York calendar date `instant` falls on. Rejects a naive `instant`.""" if instant.tzinfo is None: raise ValueError( "market_date() requires a timezone-aware datetime; a naive value silently " @@ -140,11 +96,7 @@ def previous_trading_day(self, d: date) -> date: ) def add_trading_days(self, d: date, n: int) -> date: - """Step `n` trading days from `d` — T+1 settlement is `add_trading_days(fill_date, 1)`. - - `d` itself need not be a trading day; stepping simply starts from it. `n` may be negative - to step backward, or zero to return `d` unchanged. - """ + """Step `n` trading days from `d` — T+1 settlement is `add_trading_days(fill_date, 1)`.""" step = self.next_trading_day if n >= 0 else self.previous_trading_day current = d for _ in range(abs(n)): diff --git a/backend/app/core/crypto.py b/backend/app/core/crypto.py index 86af6f9..f5055b9 100644 --- a/backend/app/core/crypto.py +++ b/backend/app/core/crypto.py @@ -1,20 +1,6 @@ """Field-level encryption at rest — the port and the persistence boundary (ADR 23). -Two columns hold secrets the application must be able to *recover*, so hashing is not an option: -`bank_link.plaid_access_token` (S2 §3.3) and the adviser TOTP secret (S0 §7.2). - -This module owns the vocabulary; it does not own an implementation. `Cipher` is a `Protocol` and -`EncryptedText` is a SQLAlchemy `TypeDecorator`, so an encrypted column is declared `Mapped[str]` -and encryption happens at the persistence boundary — a caller cannot forget to encrypt, in the same -way ADR 16 made mixing money and units impossible rather than merely discouraged. - -`app/core/` imports nothing else under `app/` (S0 §3): the adapters live in `app/integrations/` -and are injected at startup via `set_cipher`. - -Envelope layout, identical for every adapter so the stored format never depends on which one is -configured: - - version (1) ‖ wrapped_dek_len (2, big-endian) ‖ wrapped_dek ‖ nonce (12) ‖ ciphertext +Envelope layout: version(1) | wrapped_dek_len(2, big-endian) | wrapped_dek | nonce(12) | ciphertext. """ from __future__ import annotations @@ -25,7 +11,7 @@ from sqlalchemy.types import TypeDecorator ENVELOPE_VERSION = 1 -"""Bumped only by a change to the layout itself. Readers reject anything they do not know.""" +"""Bumped only by a change to the layout itself.""" NONCE_BYTES = 12 """AES-GCM standard nonce length.""" @@ -39,28 +25,16 @@ class CryptoError(Exception): class DecryptionError(CryptoError): - """Raised when a stored value cannot be authenticated and decrypted. - - Deliberately opaque: the message never distinguishes "wrong key" from "tampered ciphertext" - from "truncated envelope", because that distinction is useful to an attacker probing stored - values and useless to a legitimate caller, who can only ever act on "this value is unreadable". - """ + """Raised when a stored value cannot be authenticated and decrypted. Deliberately opaque.""" class CipherNotConfiguredError(CryptoError): - """Raised when an encrypted column is used before an adapter was installed. - - The failure mode for a misconfigured cipher must be a crash, never a plaintext write. - """ + """Raised when an encrypted column is used before an adapter was installed.""" @runtime_checkable class Cipher(Protocol): - """Encrypts and decrypts a single field value. - - Implementations must produce the envelope layout documented above, and must raise - `DecryptionError` — never return a wrong value — when authentication fails. - """ + """Encrypts/decrypts a field value. Must raise `DecryptionError`, never return a wrong value.""" def encrypt(self, plaintext: str) -> bytes: ... @@ -92,7 +66,7 @@ def get_cipher() -> Cipher: def pack_envelope(wrapped_dek: bytes, nonce: bytes, ciphertext: bytes) -> bytes: - """Assemble the wire format. Shared by every adapter so the layout is defined exactly once.""" + """Assemble the wire format. Shared by every adapter.""" if len(nonce) != NONCE_BYTES: raise CryptoError(f"nonce must be {NONCE_BYTES} bytes, got {len(nonce)}") return ( @@ -105,11 +79,7 @@ def pack_envelope(wrapped_dek: bytes, nonce: bytes, ciphertext: bytes) -> bytes: def unpack_envelope(envelope: bytes) -> tuple[bytes, bytes, bytes]: - """Split the wire format into (wrapped_dek, nonce, ciphertext). - - Every length is validated before it is used as an index, so a truncated or hostile value - raises `DecryptionError` rather than producing a short read or an IndexError. - """ + """Split the wire format into (wrapped_dek, nonce, ciphertext); rejects a truncated value.""" header = 1 + 2 if len(envelope) < header: raise DecryptionError("stored value is not a valid encryption envelope") @@ -130,14 +100,7 @@ def unpack_envelope(envelope: bytes) -> tuple[bytes, bytes, bytes]: class EncryptedText(TypeDecorator[str]): - """A `str` column whose value is encrypted on write and decrypted on read. - - Declared on a model as `Mapped[str] = mapped_column(EncryptedText())`. The plaintext never - reaches the database, and the ciphertext never reaches application code. - - Encrypted columns are opaque to SQL — they cannot be indexed, searched, or joined on. Neither - value that uses this needs to be: a Plaid access token is reached *via* its `bank_link` row. - """ + """A `str` column whose value is encrypted on write and decrypted on read. Opaque to SQL.""" impl = LargeBinary cache_ok = True diff --git a/backend/app/core/db.py b/backend/app/core/db.py index cf62fac..0fface0 100644 --- a/backend/app/core/db.py +++ b/backend/app/core/db.py @@ -1,14 +1,7 @@ -"""Database role and session-factory resolution — the vocabulary, not the wiring. +"""Database role and session-factory resolution — the vocabulary, not the wiring (S0 §3, S0 §7.3). -`app/core/` imports nothing else under `app/` (S0 §3), so it cannot reach into `app/extensions.py` -for a session. But `UnitOfWork` lives in core and needs one. The dependency is therefore inverted -exactly as `core/crypto.py` inverts the cipher: core declares the concept and a registry, and -`app/extensions.py` registers the concrete implementation at startup. - -`DbRole` lives here rather than in `extensions.py` because it is a domain concept, not an -extension instance: which credential a transaction runs under is the mechanism behind S0 §7.3's -rule that bypassing Row-Level Security is a credential boundary rather than application -discipline. `extensions.py` re-exports it, so callers outside core need not know it moved. +Core declares the concept and a registry; `app/extensions.py` registers the concrete implementation +at startup, same inversion as `core/crypto.py`'s cipher. """ from __future__ import annotations @@ -35,10 +28,7 @@ class DbRole(StrEnum): """Schema owner. Migrations only; never serves a request.""" CHAT = "chat" - """S11's `execute_read_only_sql` tool only (ADR 19). A separate least-privilege credential — - granted `SELECT` on the curated chat views alone, nothing else — so a validator bug or a - successful prompt injection cannot reach beyond what this role can already see, independent - of `APP`'s own (broader) grants.""" + """S11's `execute_read_only_sql` tool only (ADR 19) — least-privilege, curated views only.""" class SessionFactoryResolver(Protocol): @@ -48,12 +38,7 @@ def __call__(self, role: DbRole) -> Callable[[], Session]: ... class SessionFactoryNotConfiguredError(RuntimeError): - """Raised when a UnitOfWork is opened before the application registered its engines. - - The failure mode must be a loud error at the transaction boundary, never a silent fallback to - some default connection — a UnitOfWork running under the wrong credential would defeat the - RLS boundary the roles exist to enforce. - """ + """Raised when a UnitOfWork is opened before the application registered its engines.""" _resolver: SessionFactoryResolver | None = None diff --git a/backend/app/core/errors.py b/backend/app/core/errors.py index 0bdaa2a..aa0574e 100644 --- a/backend/app/core/errors.py +++ b/backend/app/core/errors.py @@ -1,17 +1,5 @@ -"""RFC 9457 `application/problem+json` error hierarchy (S0 §8). - -Every route in the system eventually fails one of a handful of ways — bad input, a missing or -forbidden resource, an authentication gap, a conflicting write, too many requests. `AppError` gives -each of those one shape a frontend can branch on: a stable `code`, never a message a future -copy-edit could quietly change. - -`to_problem()` is deliberately the *only* thing that reaches a client. `AppError.detail` exists -purely for server-side logging — a SQL fragment, an internal ID, a token, whatever a caller -attaches to explain what went wrong internally — and must never be threaded into the response body. -The application's error handler (`app/__init__.py`) logs `detail` and renders `to_problem()`; this -module does not wire itself into Flask, so a route or job can raise `AppError` before any web -framework is involved. -""" +"""RFC 9457 `application/problem+json` error hierarchy (S0 §8). `to_problem()` is the only thing +that reaches a client; `detail` is server-side logging only, never rendered.""" from __future__ import annotations @@ -19,30 +7,24 @@ class AppError(Exception): - """Base of the problem+json hierarchy. Constructors never require `code`. - - `status`, `title`, and `code` are per-class defaults a subclass overrides; `code` can also be - overridden per raise (`ValidationError(code="insufficient_investable_cash")`) so a later wave - can mint a stable, domain-specific branch code without a new class for every one. - """ + """Base of the problem+json hierarchy. `status`/`title`/`code` are per-class defaults, `code` + can also be overridden per raise.""" status: int = 500 title: str = "Internal Server Error" code: str = "internal_error" type_uri: str = "about:blank" - """RFC 9457 `type`. "about:blank" (no more specific URI minted yet) means `title` documents - the problem type, which is exactly S0 §8's model — `code` is the actual machine-readable - discriminant, not `type`.""" + """RFC 9457 `type`; `code` is the actual machine-readable discriminant, not `type`.""" def __init__(self, detail: str | None = None, *, code: str | None = None) -> None: super().__init__(detail if detail is not None else self.title) self.detail = detail - """Server-side only. Never read by `to_problem()`; log it explicitly if it helps triage.""" + """Server-side only. Never read by `to_problem()`.""" if code is not None: self.code = code def to_problem(self, correlation_id: str) -> dict[str, Any]: - """The entire client-visible surface of this error. No other attribute is ever exposed.""" + """The entire client-visible surface of this error.""" return { "type": self.type_uri, "title": self.title, @@ -85,11 +67,8 @@ class UnauthenticatedError(AppError): class ConflictError(AppError): - """The request conflicts with existing state (409). - - S0 §8's idempotency rule: a repeated `Idempotency-Key` whose body hash does not match the - original request is rejected with this, rather than silently replaying or overwriting. - """ + """The request conflicts with existing state (409). Also raised for an idempotency key reused + with a different body hash (S0 §8).""" status = 409 title = "Conflict" diff --git a/backend/app/core/logging.py b/backend/app/core/logging.py index d2b9c95..38fb258 100644 --- a/backend/app/core/logging.py +++ b/backend/app/core/logging.py @@ -1,12 +1,5 @@ -"""Structured logging and per-request correlation IDs (S0 §7.4, OWASP A09). - -One correlation ID per request, echoed on the response and attached to every log line emitted -while handling it, so a customer report can be joined to the exact server-side trace. - -Secrets and PII never reach a log (root `CLAUDE.md`). This module provides the plumbing; keeping -payloads out of log calls is the caller's responsibility, and `views/` schemas are the enforcement -point for what leaves the process at all. -""" +"""Structured logging and per-request correlation IDs (S0 §7.4, OWASP A09). Secrets and PII never +reach a log — this module is the plumbing; callers keep them out of calls.""" from __future__ import annotations @@ -44,11 +37,7 @@ def _add_correlation_id( def configure_logging(*, json_output: bool, level: int = logging.INFO) -> None: - """Configure structlog once at startup. - - JSON in deployed environments so Application Insights can index fields (ADR 20); a readable - console renderer in development, where a human is the consumer. - """ + """Configure structlog once at startup. JSON in deployed envs (ADR 20), console in dev.""" renderer: structlog.types.Processor = ( structlog.processors.JSONRenderer() if json_output diff --git a/backend/app/core/money.py b/backend/app/core/money.py index 2af4d12..e916c3d 100644 --- a/backend/app/core/money.py +++ b/backend/app/core/money.py @@ -1,33 +1,9 @@ """Typed money/units/price value objects — dimension-mixing as a type error (ADR 16, S0 §4). -The brief calls units-vs-money confusion "the classic day-one bug." S1 §3.3 closes the storage -half with a database `CHECK` constraint; this module closes the computation half. In plain -`Decimal`, nothing stops `quantity_units + amount_money` from running to completion and producing -a number that is neither a valid money nor a valid unit figure, reaching a customer screen or a tax -export before any database constraint has a chance to reject it. - -Three immutable value objects — `Money` (`NUMERIC(18,4)`), `Units` (`NUMERIC(28,6)`, six places per -FR-11), `Price` (`NUMERIC(18,6)`) — make that impossible: - -- Constructed only from `str`, `int`, `Decimal`, or another instance of the *same* type. A `float` - raises `TypeError` unconditionally — binary floating point has no place in a regulated ledger. -- Quantized at construction with `ROUND_HALF_EVEN` (banker's rounding), which avoids the systematic - upward bias of always rounding a half up. -- Same-dimension `+`/`-`; three legal cross-dimension operations, all FR-11's `value = units x - price` run in some direction: `Price * Units -> Money` (commutative with `Units * Price`), - `Money / Units -> Price` (S3's `order.average_fill_price`), and `Money / Price -> Units` (S9's - `RebalanceOrderService`, sizing an order quantity from a dollar drift amount). Every other - cross-dimension arithmetic op raises `TypeError` — most of it statically, under `mypy --strict`, - because the operand of `__add__`/`__mul__`/`__truediv__` is typed `Self` or an explicit sibling - type rather than `object`. -- Each type has a SQLAlchemy `TypeDecorator` so a `Mapped[Money]` column reads back as `Money`, - never a bare `Decimal` a caller must remember the meaning of. -- Each type is Pydantic-native (`__get_pydantic_core_schema__`): parses from a JSON string and - serializes back to one in JSON mode, so a JSON *number* — IEEE-754, and lossy — never appears on - the wire for a money or unit value. - -`app/core/` imports nothing else under `app/` (S0 §3); this module depends only on the standard -library, SQLAlchemy, and Pydantic. +`Money` (`NUMERIC(18,4)`), `Units` (`NUMERIC(28,6)`, FR-11), `Price` (`NUMERIC(18,6)`): immutable, +`float`-rejecting, `ROUND_HALF_EVEN`-quantized, same-dimension arithmetic only plus FR-11's three +legal cross-dimension ops (`Price * Units -> Money`, `Money / Units -> Price`, `Money / Price -> +Units`). """ from __future__ import annotations @@ -47,11 +23,7 @@ def _scalar_to_decimal(value: object, *, typename: str) -> Decimal: - """Convert an `int`/`Decimal` scalar for multiplication/division. Never a `float` or `bool`. - - Shared by every concrete type's scalar `*`/`/` so the float/bool rejection is enforced in one - place, in addition to the static `int | Decimal` parameter type each dunder declares. - """ + """Convert an `int`/`Decimal` scalar for multiplication/division. Never a `float` or `bool`.""" if isinstance(value, bool): raise TypeError(f"{typename} scalar operations do not accept bool") if isinstance(value, float): @@ -69,11 +41,7 @@ def _scalar_to_decimal(value: object, *, typename: str) -> Decimal: class _QuantizedDecimal: """Shared machinery for `Money`/`Units`/`Price`: parsing, quantization, and same-type ops. - - Not exported and never instantiated directly — each concrete type declares its own `_scale` - (decimal places) and `_precision` (total significant digits, matching its `NUMERIC` column) and - inherits everything else. - """ + Not exported; each concrete type declares its own `_scale`/`_precision`.""" __slots__ = ("_value",) @@ -110,8 +78,7 @@ def __init__(self, value: str | int | Decimal | Self) -> None: quantized = decimal_value.quantize(self._quantum(), rounding=ROUND_HALF_EVEN) if quantized == 0: - # Quantizing a tiny negative value (e.g. -0.00001 at 4 places) yields Decimal's - # negative zero, which would otherwise serialize as the confusing "-0.0000". + # Avoids serializing Decimal's negative zero as "-0.0000". quantized = quantized.copy_abs() self._validate_precision(quantized) object.__setattr__(self, "_value", quantized) @@ -189,14 +156,7 @@ def __ge__(self, other: Self) -> bool: def allocate(self, weights: Sequence[int]) -> list[Self]: """Split into `len(weights)` parts, proportional to `weights`, summing exactly to `self`. - - Pro-rata division never divides evenly; non-negotiable #6 requires the residual to be - assigned deterministically rather than left to float error or arbitrary ordering. This - uses the largest-remainder method: compute each part's exact fractional share, floor it to - the type's scale, then hand the leftover smallest units one at a time to the parts with the - largest fractional remainder, breaking ties by ascending weight index. Both the floor and - the tie-break are deterministic, so the same weights always produce the same split. - """ + Largest-remainder method, tie-break by ascending weight index (non-negotiable #6).""" if not weights: raise ValueError("allocate requires at least one weight") if any(w < 0 for w in weights): @@ -245,8 +205,7 @@ def validate(value: Any) -> _QuantizedDecimal: try: return cls(value) except TypeError as exc: - # A programming error (Money(1500.00)) is a TypeError; a value arriving through - # request validation must instead surface as a normal Pydantic ValidationError. + # Surface as a Pydantic ValidationError, not a raw TypeError. raise ValueError(str(exc)) from exc return core_schema.no_info_plain_validator_function( @@ -281,16 +240,7 @@ def __truediv__( self, other: Money | Units | Price | int | Decimal ) -> Decimal | Price | Units | Self: """`Money / Money` -> ratio, `Money / Units` -> `Price`, `Money / Price` -> `Units`, - `Money / scalar` -> `Money`. - - `Money / Units -> Price` and `Money / Price -> Units` are FR-11's two directions of - `value = units x price`, run backward. The `Units` direction shipped first, for S3's - `order.average_fill_price`; `Price` was deliberately withheld at the time ("add it - deliberately when a real caller does") until S9's `RebalanceOrderService` (S9 §6) became - that caller: converting a dollar drift amount into an order quantity — `quantity = notional - / price` — has no route that avoids unwrapping to a bare `Decimal` either, the identical - shape of gap ADR 16 already accepted the first exception for. - """ + `Money / scalar` -> `Money` — FR-11's `value = units x price`, run backward (ADR 16).""" if isinstance(other, Money): if other._value == 0: raise ZeroDivisionError("Money division by zero Money") @@ -376,10 +326,7 @@ def __truediv__(self, other: Price | int | Decimal) -> Decimal | Self: class MoneyType(TypeDecorator[Money]): - """Maps `Money` to `NUMERIC(18,4)`. - - A `Mapped[Money]` column reads back as `Money`, never a bare `Decimal`. - """ + """Maps `Money` to `NUMERIC(18,4)`; a `Mapped[Money]` column reads back as `Money`.""" impl = Numeric(18, 4) cache_ok = True diff --git a/backend/app/core/pagination.py b/backend/app/core/pagination.py index a157691..bec2f8a 100644 --- a/backend/app/core/pagination.py +++ b/backend/app/core/pagination.py @@ -1,24 +1,6 @@ -"""Cursor-based pagination (S0 §8). - -Offset pagination (`LIMIT`/`OFFSET`) on an append-only, ever-growing ledger degrades as the offset -grows, and — worse — can skip or duplicate rows when a concurrent insert shifts the window mid-scan. -This module exists so no list endpoint (transaction history, tax lots, reconciliation breaks) has -to reach for `OFFSET` at all: a cursor names the last row a caller has seen by its sort key, and the -next page asks for rows strictly after it. - -A cursor must be built from a **compound, unique sort key** — `(timestamp, id)`, never a bare -timestamp. Two rows sharing the same instant are unremarkable in a system that posts several ledger -legs together in one transaction; a cursor that cannot break the tie deterministically will skip or -repeat whichever row sits on the page boundary. - -The cursor is opaque to the client (a base64url token, not a raw offset or row id to probe) and -tamper-evident: the encoded payload carries a checksum of itself, so a corrupted, truncated, or -hand-edited cursor is rejected as a clean `ValidationError` — never a 500, never a silently -mis-paged result. The checksum is a *corruption* detector, not an authorization boundary: every -repository query built from a decoded cursor is still tenant-scoped and re-validated like any other -input, so a client crafting its own well-formed cursor gains nothing beyond choosing which of its -own rows to page from. -""" +"""Cursor-based pagination (S0 §8). Avoids `OFFSET` skip/duplicate bugs on an append-only ledger — +a cursor names the last row seen by a compound, unique sort key (e.g. `(timestamp, id)`), opaque to +the client and tamper-evident via checksum.""" from __future__ import annotations @@ -41,22 +23,18 @@ DEFAULT_PAGE_SIZE = 50 MAX_PAGE_SIZE = 200 -"""Enforced on every list endpoint (OWASP API4 — unrestricted resource consumption). No caller, -including an internal one, may request an unbounded page.""" +"""Enforced on every list endpoint (OWASP API4 — unrestricted resource consumption).""" _MAX_CURSOR_LENGTH = 2048 -"""Generously larger than any realistic sort key; rejects an oversized token before it is parsed.""" +"""Rejects an oversized token before it is parsed.""" _CHECKSUM_BYTES = 16 @dataclass(frozen=True, slots=True) class Page[T]: - """One page of a cursor-paginated list. - - `next_cursor` is `None` exactly when there is no further page. `has_more` is derived from it - rather than stored separately, so the two can never disagree with each other. - """ + """One page of a cursor-paginated list. `has_more` is derived from `next_cursor`, never stored + separately.""" items: tuple[T, ...] next_cursor: str | None @@ -72,12 +50,7 @@ def normalize_limit( default: int = DEFAULT_PAGE_SIZE, maximum: int = MAX_PAGE_SIZE, ) -> int: - """Validate a client-supplied page size, or apply the default when the client gave none. - - Rejects a non-positive or oversized value outright, rather than silently clamping it — clamping - would let a caller believe it asked for 100,000 rows and quietly received 200, which is a worse - failure mode for a paging client than an explicit `422`. - """ + """Validate a client-supplied page size, or apply the default. Rejects rather than clamps.""" if limit is None: return default if limit <= 0: @@ -88,11 +61,8 @@ def normalize_limit( def encode_cursor(*values: CursorValue) -> str: - """Encode a compound sort key into an opaque, tamper-evident cursor. - - Pass every component of the sort key the query orders by, in order — e.g. - `encode_cursor(posting.recorded_at.isoformat(), posting.id)`. - """ + """Encode a compound sort key into an opaque, tamper-evident cursor, e.g. + `encode_cursor(posting.recorded_at.isoformat(), posting.id)`.""" if not values: raise ValueError("encode_cursor requires at least one sort-key value") payload = json.dumps(list(values), separators=(",", ":")).encode("utf-8") @@ -101,11 +71,8 @@ def encode_cursor(*values: CursorValue) -> str: def decode_cursor(cursor: str) -> tuple[CursorValue, ...]: - """Decode and verify a cursor produced by `encode_cursor`. - - Never raises anything but `ValidationError`, and never echoes the offending input back in the - error — a malformed cursor is client input to reject cleanly, not server state to explain. - """ + """Decode and verify a cursor produced by `encode_cursor`. Never raises anything but + `ValidationError`; never echoes the offending input back.""" if not cursor or len(cursor) > _MAX_CURSOR_LENGTH: raise ValidationError("invalid pagination cursor") @@ -144,12 +111,7 @@ def paginate[T]( cursor_key: Callable[[T], Sequence[CursorValue]], ) -> Page[T]: """Build a `Page` from rows already fetched with `limit + 1`, sorted ascending by the same - compound key `cursor_key` extracts. - - Fetching one extra row is what makes `has_more` free: if the `limit + 1`-th row came back, - another page exists and its cursor is the compound key of the last row *kept* on this page — - no second `COUNT` query, and no risk of an off-by-one from re-deriving "more" a different way. - """ + compound key `cursor_key` extracts. The extra row is what makes `has_more` free — no `COUNT`.""" if len(rows) > limit: page_items = tuple(rows[:limit]) next_cursor = encode_cursor(*cursor_key(page_items[-1])) diff --git a/backend/app/core/repository.py b/backend/app/core/repository.py index 6cae25a..c954268 100644 --- a/backend/app/core/repository.py +++ b/backend/app/core/repository.py @@ -1,33 +1,9 @@ """`BaseRepository` — application-layer tenant scoping and the append-only guard (S0 §5, ADR 14). -Two independent defenses this module provides, both belt-and-suspenders above the database: - -- **Tenant scoping.** Every query a repository builds is filtered by the `customer_id` carried on - its `UnitOfWork` — taken from there, never from a Flask global (`app/core/uow.py`). This is the - *application-layer* half of S0 §7.3's defense-in-depth; Postgres RLS is the control that still - holds if this code is bypassed or buggy, and this is the control that fails fast, before a query - is even sent, for the common case. An adviser/admin session (`SessionRole.ADVISER`/`ADMIN`) skips - the filter deliberately — FR-31's cross-customer reconciliation screen needs exactly that, and - RLS's role-aware policy (ADR 17) is what still gates it at the database. `customer_id_column` is - optional: a table with no customer identity at all (`inbound_event`, `job_outbox`, `job_run` — - internal operational/audit tables, not customer data) omits it, and `_tenant_scoped()` raises - rather than building a nonsense filter if such a repository ever calls it. -- **Append-only enforcement.** A repository subclass for an append-only aggregate (`journal_entry`, - `posting`, `order_event`, `published_snapshot`, ...) sets `append_only = True`, and an UPDATE or - DELETE about to be flushed for that entity is rejected before it reaches the database — the - ORM-layer half of the guarantee S1 §6's revoked grants and ADR 17's deferred balance trigger - backstop at the database. Three independent layers for the one invariant this ledger cannot get - wrong (NFR-1, NFR-2). - -**The `as_of: Watermark` shape.** `find_as_of()` is built the way ADR 6 requires every bitemporal -read to be: `as_of` is required and keyword-only, with no default, so a caller who forgets it gets a -`TypeError` before the code ships, not a live figure silently mislabelled as published. A repository -for an aggregate with no bitemporal dimension simply never calls this method — it exists here to be -inherited and to fix the shape Wave 3's ledger repositories reuse, not to be imposed on everything. - -Services depend on their aggregate's own `Protocol` (the same pattern S0 §5 uses in -`integrations/ports.py`), never on `BaseRepository` directly — a test substitutes a fake by -implementing that Protocol structurally, with no import of this module at all. +Belt-and-suspenders above the database: tenant scoping filters every query by +`UnitOfWork.customer_id` (adviser/admin sessions skip it, FR-31/ADR 17), and `append_only = True` +rejects an UPDATE/DELETE before flush (S1 §6, ADR 17). `find_as_of()`'s `as_of` is required +keyword-only with no default (ADR 6). """ from __future__ import annotations @@ -50,21 +26,11 @@ class AppendOnlyViolationError(RuntimeError): - """Raised when an UPDATE or DELETE is about to be flushed for an append-only aggregate. - - The database is the guarantee of record (S1 §6's revoked grants, ADR 17's deferred balance - trigger); this catches the same mistake one layer earlier, in the application, before the - statement is even sent. - """ + """Raised when an UPDATE or DELETE is about to be flushed for an append-only aggregate.""" class BaseRepository[ModelT]: - """One instance per aggregate, bound to one `UnitOfWork`. See module docstring. - - Subclasses pass their entity type and tenant/watermark columns to `__init__` — a repository is - generic over any mapped entity, not tied to a particular one via inheritance-time - parameterization, which keeps this class usable by an entity `app/core` has never heard of. - """ + """One instance per aggregate, bound to one `UnitOfWork`. See module docstring.""" append_only: ClassVar[bool] = False """Set `True` on an aggregate's repository subclass to forbid UPDATE/DELETE (ADR 1, S1 §6).""" @@ -93,12 +59,7 @@ def add(self, instance: ModelT) -> None: self.session.add(instance) def find_as_of(self, *, as_of: Watermark, **equality_filters: Any) -> Sequence[ModelT]: - """Generic bitemporal, tenant-scoped read. `as_of` has no default — see module docstring. - - `equality_filters` are plain `column=value` matches against the entity, e.g. - `find_as_of(as_of=watermark, order_id=order_id)`. A concrete repository with a richer - query shape overrides or wraps this rather than forcing every read through it. - """ + """Generic bitemporal, tenant-scoped read, e.g. `find_as_of(as_of=wm, order_id=id)`.""" if self._recorded_at_column is None: raise RuntimeError( f"{type(self).__name__} was not configured with a recorded_at_column; " @@ -111,11 +72,7 @@ def find_as_of(self, *, as_of: Watermark, **equality_filters: Any) -> Sequence[M return self.session.execute(statement).scalars().all() def _tenant_scoped(self, statement: Select[tuple[ModelT]]) -> Select[tuple[ModelT]]: - """Apply the customer filter every subclass query should build on. - - Adviser/admin sessions read across customers deliberately (FR-31); RLS's role-aware policy - is what actually gates that at the database (ADR 17), not this method. - """ + """Apply the customer filter. Adviser/admin sessions skip it deliberately (FR-31).""" if self._uow.role in (SessionRole.ADVISER, SessionRole.ADMIN): return statement if self._customer_id_column is None: @@ -131,13 +88,8 @@ def _tenant_scoped(self, statement: Select[tuple[ModelT]]) -> Select[tuple[Model return statement.where(self._customer_id_column == customer_id) def _reject_mutation(self, session: Session, flush_context: Any, instances: Any) -> None: - """`before_flush` handler, registered only when `append_only` is `True`. - - Inspects `session.dirty`/`session.deleted` rather than intercepting a repository method, - because the guarantee this exists for is "no code path can mutate this row" — including one - that reaches the entity through a different repository, or through a plain - `session.add(existing_instance)` after changing an attribute. - """ + """`before_flush` handler, registered only when `append_only` is `True`. Inspects + `session.dirty`/`session.deleted` so no code path can mutate this row.""" for obj in session.dirty: if isinstance(obj, self._entity): raise AppendOnlyViolationError( diff --git a/backend/app/core/security.py b/backend/app/core/security.py index be1c945..89471c6 100644 --- a/backend/app/core/security.py +++ b/backend/app/core/security.py @@ -1,12 +1,5 @@ """Declarative authorization decorators (S0 §7.2): `@requires_role`, `@requires_ownership`, -`@audited`. - -`@audited` must write its `admin_audit_log` row inside the *same* `UnitOfWork`/session as the -action it decorates (S0 §7.2, ADR 15) — but `app/core/` may import nothing else under `app/` -(S0 §3), so it cannot import the concrete `AdminAuditLog` model from `app/models/ops/`. `AuditSink` -inverts that dependency exactly as `core/crypto.py` inverts `Cipher`: this module declares the -Protocol and a process-wide registry, and the concrete implementation (backed by the real -`admin_audit_log` table) is installed once at startup via `set_audit_sink()`. +`@audited`. `AuditSink` inverts the `AdminAuditLog` dependency (S0 §3), like `crypto.py`'s `Cipher`. """ from __future__ import annotations @@ -29,12 +22,8 @@ @runtime_checkable class AuditSink(Protocol): - """Persists one `admin_audit_log` row inside the caller's `UnitOfWork` (S0 §7.2). - - The implementation must stage the row via `uow.session`/an append-only repository bound to - that same `uow` — never open its own transaction — so the audit write and the action it - records commit or roll back together. - """ + """Persists one `admin_audit_log` row inside the caller's `UnitOfWork` (S0 §7.2). Must stage + via that same `uow`, never open its own transaction.""" def record( self, @@ -91,10 +80,7 @@ def decorated_function(*args: Any, **kwargs: Any) -> Any: def requires_ownership( customer_id_param: str = "customer_id", ) -> Callable[[Callable[..., Any]], Callable[..., Any]]: - """ - Asserts the target customer_id matches the authenticated customer, or the principal is an - authorized staff member. - """ + """Asserts target customer_id matches the authenticated customer, or the principal is staff.""" def decorator(f: Callable[..., Any]) -> Callable[..., Any]: @functools.wraps(f) @@ -131,16 +117,8 @@ def decorated_function(*args: Any, **kwargs: Any) -> Any: def audited( action: str, target_customer_id_param: str = "customer_id" ) -> Callable[[Callable[..., Any]], Callable[..., Any]]: - """ - Writes to admin_audit_log inside the same UnitOfWork as the action, via the installed - `AuditSink` (see module docstring). - - `target_customer_id` is optional (`admin_audit_log.target_customer_id` is nullable): not every - audited action has a single-customer target -- e.g. resolving a `reconciliation_break` with no - customer attribution (S7 §5.2). A caller that omits `target_customer_id_param` entirely, or - passes it as `None`, is treated the same way: the action is still recorded, just with no - customer to index it under. - """ + """Writes to admin_audit_log inside the same UnitOfWork as the action, via the installed + `AuditSink`. `target_customer_id` is optional — not every audited action has one (S7 §5.2).""" def decorator(f: Callable[..., Any]) -> Callable[..., Any]: @functools.wraps(f) diff --git a/backend/app/core/uow.py b/backend/app/core/uow.py index 3936f32..6b11307 100644 --- a/backend/app/core/uow.py +++ b/backend/app/core/uow.py @@ -1,36 +1,9 @@ """`UnitOfWork` — the transaction boundary (S0 §5, ADR 14). -One instance per HTTP request, one per job execution step. A service method either fully succeeds -and commits **once** through the `UnitOfWork` it was handed, or raises and the whole unit rolls -back — no service ever opens its own transaction or calls `session.commit()` directly. - -**Tenant context is passed in explicitly, never read from `flask.g`.** `UnitOfWork(customer_id=..., -role=...)` is a plain constructor call that works identically inside a request, inside a scheduled -job, and inside a unit test — none of which can assume a Flask request context exists. A `core` -module reaching into a web-framework global would make the entire persistence layer untestable -outside a request and would quietly couple jobs to Flask. - -At the start of every transaction this issues `SELECT set_config('app.role', ..., true)` and -`SELECT set_config('app.customer_id', ..., true)` — the `true` (`is_local`) argument is -`set_config`'s parameterized equivalent of `SET LOCAL`: transaction-scoped, and gone the instant -the transaction ends, which is exactly what S0 §7.3's RLS policies rely on. `set_config` is used -instead of a literal `SET LOCAL app.role = '...'` string specifically so the value is a bound -parameter, never string-interpolated SQL (root `CLAUDE.md`: parameterized queries only). - -**Extending `UnitOfWork` with repositories.** This module intentionally ships zero repository -accessors — `uow.ledger`, `uow.orders`, and the rest belong to the wave that defines each -aggregate's repository. The extension point is ordinary subclassing plus `functools.cached_property` -bound to `self.session`, so each accessor is fully typed and mypy-checked, with no registry, no -string keys, and no dynamic attribute magic to work around: - - class LedgerUnitOfWork(UnitOfWork): - @cached_property - def ledger(self) -> LedgerRepository: - return SqlLedgerRepository(self) - - with LedgerUnitOfWork(customer_id=customer_id, role=SessionRole.CUSTOMER) as uow: - uow.ledger.post(entry) - uow.commit() +One instance per HTTP request/job step; commits **once** or rolls back on raise. Tenant context is +passed in explicitly, never read from `flask.g`. Issues `SELECT set_config(...)` (`SET LOCAL`- +equivalent, bound parameter) for S0 §7.3's RLS policies. Subclasses add repository accessors via +`functools.cached_property` bound to `self.session`. """ from __future__ import annotations @@ -51,11 +24,8 @@ def ledger(self) -> LedgerRepository: class SessionRole(StrEnum): - """The business role behind the current session — what S0 §7.3's RLS policy reads as - `app.role`. Distinct from `DbRole` (`app/core/db.py`), which selects a *database - credential*: a customer, an adviser, and an admin all authenticate through the same `APP` - database role, and RLS is what tells their traffic apart at the row level. - """ + """The business role behind the session — what S0 §7.3's RLS policy reads as `app.role`. + Distinct from `DbRole`, which selects a database credential.""" CUSTOMER = "customer" ADVISER = "adviser" @@ -63,12 +33,7 @@ class SessionRole(StrEnum): class UnitOfWork: - """The transaction boundary. See module docstring for the extension mechanism. - - Not reentrant: one instance is good for exactly one `with` block, matching "one per request, - one per job step" — reusing an instance across two transactions would let a repository cached - on it silently keep operating against an already-closed session. - """ + """The transaction boundary; see module docstring. Not reentrant: one instance per `with`.""" def __init__( self, @@ -140,22 +105,18 @@ def __exit__( session = self.session try: if not self._finalized: - # Never commit implicitly: an exception, a missed commit(), and a plain fall-through - # all end the same way — rolled back. + # Never commit implicitly. session.rollback() finally: session.close() self._session = None def commit(self) -> None: - """Commit the transaction. Called at most once, and only after every write in this unit - has succeeded — S0 §5's "exactly one commit point per operation".""" + """Commit the transaction. Called at most once — S0 §5's "exactly one commit point".""" self.session.commit() self._finalized = True def rollback(self) -> None: - """Explicitly discard the transaction. Rarely needed directly — raising is the normal way - to trigger a rollback — but available for a service that decides mid-operation that its - own work should not proceed without treating that decision as an error.""" + """Explicitly discard the transaction. Rarely needed — raising triggers rollback.""" self.session.rollback() self._finalized = True diff --git a/backend/app/core/watermark.py b/backend/app/core/watermark.py index c4b6dfe..b44a881 100644 --- a/backend/app/core/watermark.py +++ b/backend/app/core/watermark.py @@ -1,20 +1,6 @@ -"""Bitemporal read watermark (ADR 1, ADR 6). - -Every read of the ledger answers one of two different questions, and conflating them is the -single most damaging mistake this system can make: - -- **Live / as-corrected** — "what is true now, including every correction since." Screen views, - current balances, ad-hoc queries. -- **As-published** — "what did we tell the customer at period close." Pinned to the `recorded_at` - watermark stored with the snapshot, and it must return the same figure forever (ADR 6's - `derive(period, recorded_at <= publish_watermark) == snapshot` invariant, which is NFR-1's - actual tamper detector). - -ADR 6: "Every consumer of 'the published figure' must be explicit about which watermark it wants, -or it will silently get the live, as-corrected figure instead — a labelling discipline that must -be enforced at the query layer, not left to callers to remember." That is why repository methods -take `as_of: Watermark` as a **required keyword-only parameter with no default**: omitting it is a -type error caught by `mypy --strict`, not a live figure quietly mislabelled as published. +"""Bitemporal read watermark (ADR 1, ADR 6). Distinguishes "live/as-corrected" from "as-published" +reads; repository methods take `as_of: Watermark` as required keyword-only with no default, so +omitting it is a `mypy --strict` type error, not a mislabelled live figure. """ from __future__ import annotations @@ -25,11 +11,8 @@ @dataclass(frozen=True, slots=True) class Watermark: - """The `recorded_at` ceiling a bitemporal query filters on. - - Immutable, and constructed only through `live()` or `as_published()` — the two named readings - are the whole point, so a bare cutoff cannot be passed around without saying which it is. - """ + """The `recorded_at` ceiling a bitemporal query filters on. Immutable, constructed only + through `live()` or `as_published()`.""" cutoff: datetime """Inclusive upper bound: rows with `recorded_at <= cutoff` are visible. Always tz-aware UTC.""" @@ -47,21 +30,13 @@ def __post_init__(self) -> None: @classmethod def live(cls, *, now: datetime | None = None) -> Watermark: - """An as-corrected read: everything recorded up to this moment. - - The instant is captured once, at construction, rather than re-evaluated per query. Two - reads inside one unit of work therefore see the same world — without this, a correction - landing mid-transaction could make a balance and the postings behind it disagree. - """ + """An as-corrected read: everything recorded up to now, captured once at construction.""" return cls(cutoff=(now or datetime.now(UTC)).astimezone(UTC), is_live=True) @classmethod def as_published(cls, recorded_at: datetime) -> Watermark: - """A read pinned to a publication's stored watermark (ADR 6). - - Feed this the `recorded_at` saved alongside the snapshot, never `now()`; the point is that - the same query returns the same figure forever, however many corrections follow. - """ + """A read pinned to a publication's watermark (ADR 6); feed it `recorded_at`, not + `now()`.""" if recorded_at.tzinfo is None: raise ValueError("as_published requires a timezone-aware recorded_at") return cls(cutoff=recorded_at.astimezone(UTC), is_live=False) diff --git a/backend/app/extensions.py b/backend/app/extensions.py index 7d39d7e..1c5da95 100644 --- a/backend/app/extensions.py +++ b/backend/app/extensions.py @@ -1,15 +1,6 @@ -"""Shared extension and engine instances. +"""Shared extension and engine instances, initialised by `app/__init__.py`'s factory. -Declared here, initialised in `app/__init__.py`'s factory — never constructed inline in a -controller or service (`backend/CLAUDE.md`). - -Three database engines, not one, because S0 §7.3 makes the RLS bypass a credential boundary: -the web API's engine uses a role without `BYPASSRLS` and is structurally incapable of reading -across tenants, whatever a future request-handling bug does. Jobs and the outbox worker use the -`worker` engine; migrations use `owner`. - -`DbRole` itself lives in `app/core/db.py` — `app/core/` may not import this module (S0 §3), and -`UnitOfWork` needs the concept. It is re-exported here so callers outside core need not care. +Four DB engines (one per `DbRole`) enforce the RLS/credential boundary from S0 §7.3. """ from __future__ import annotations @@ -60,9 +51,7 @@ def init_engines(settings: Settings) -> None: engine = create_engine( url, pool_pre_ping=True, - # NUMERIC must arrive as Decimal, never float — a float in a money path is a bug - # (S0 §10.9). psycopg3 already does this; stated so a future driver swap cannot - # silently change it. + # NUMERIC must arrive as Decimal, never float (S0 §10.9). echo=False, future=True, ) diff --git a/backend/app/integrations/alpaca/broker_adapter.py b/backend/app/integrations/alpaca/broker_adapter.py index cb75f30..14e5aa7 100644 --- a/backend/app/integrations/alpaca/broker_adapter.py +++ b/backend/app/integrations/alpaca/broker_adapter.py @@ -1,14 +1,8 @@ """`AlpacaBrokerAdapter` (S3 §6, ADR 21) — `BrokerPort → Alpaca Paper Trading`. -`TimeInForce.DAY`: Alpaca requires `day` for fractional-quantity orders (ADR 21/S9 §5 — every -order this system places uses an exact fractional quantity, never rounded to a whole share), so -this is not a tunable choice but the only value Alpaca's own API accepts for the order shapes this -system generates. - -Raises `alpaca.common.exceptions.APIError` on a rejected submission or transport failure; never -caught here. `submit_order` runs inside an outbox task handler (S3 §4), and the outbox worker's own -exponential-backoff retry (`app/workers/outbox.py`) is the retry mechanism — an adapter-level retry -here would duplicate it with its own independent backoff clock. +`TimeInForce.DAY` is the only value Alpaca accepts for fractional-quantity orders (ADR 21/S9 §5). +Raises `alpaca.common.exceptions.APIError` uncaught; the outbox worker's own retry is the retry +mechanism, never an adapter-level one. """ from __future__ import annotations @@ -48,9 +42,7 @@ def submit_order( ) result = self._client.submit_order(order_data=request) if not isinstance(result, AlpacaOrder): - # Only reachable if `TradingClient` were constructed with `raw_data=True`, which this - # adapter never does — narrows the SDK's own broader return type for mypy, and fails - # loudly rather than returning a handle built from an unvalidated dict. + # Only reachable with raw_data=True, which this adapter never sets. raise TypeError(f"expected an Alpaca Order, got {type(result).__name__}") return BrokerOrderHandle( broker_order_id=str(result.id), client_order_id=result.client_order_id diff --git a/backend/app/integrations/alpaca/calendar_adapter.py b/backend/app/integrations/alpaca/calendar_adapter.py index 7f4a755..c7a2868 100644 --- a/backend/app/integrations/alpaca/calendar_adapter.py +++ b/backend/app/integrations/alpaca/calendar_adapter.py @@ -1,8 +1,5 @@ -"""`AlpacaCalendarAdapter` (S4 §3.4, ADR 12) — `CalendarPort → Alpaca`. - -Populates `market_calendar_cache`; `app/core/clock.py`'s `MarketClock` never calls this directly — -it queries the cache through `CachedTradingCalendar` (`app/models/marketdata/trading_calendar.py`), -per `CalendarPort`'s own docstring in `ports.py`. +"""`AlpacaCalendarAdapter` (S4 §3.4, ADR 12) — `CalendarPort → Alpaca`. Populates +`market_calendar_cache`; `MarketClock` queries it via `CachedTradingCalendar`, never this directly. """ from __future__ import annotations @@ -20,9 +17,7 @@ class AlpacaCalendarAdapter: - """An empty `get_calendar` result means `market_date` is not a trading day (a weekend or a - market holiday) — Alpaca's calendar endpoint only ever lists trading days, so absence *is* the - signal, distinct from `market_calendar_cache`'s own "not yet fetched" absence (S4 §3.4).""" + """An empty `get_calendar` result means `market_date` is not a trading day (weekend/holiday).""" def __init__(self, *, api_key_id: str, api_secret_key: str, paper: bool = True) -> None: self._client = TradingClient(api_key=api_key_id, secret_key=api_secret_key, paper=paper) diff --git a/backend/app/integrations/alpaca/market_data_adapter.py b/backend/app/integrations/alpaca/market_data_adapter.py index 4b30fab..38e54a2 100644 --- a/backend/app/integrations/alpaca/market_data_adapter.py +++ b/backend/app/integrations/alpaca/market_data_adapter.py @@ -1,8 +1,5 @@ -"""`AlpacaMarketDataAdapter` (S4 §4, ADR 12) — `MarketDataPort → Alpaca`. - -Owns only stock-data-API calls; `AlpacaCalendarAdapter` (the sibling file in this package) owns the -trading-calendar API. `orders-engineer` owns `broker_adapter.py`/`trade_updates_consumer.py` in this -same directory — different files, same Alpaca account, no shared state between them. +"""`AlpacaMarketDataAdapter` (S4 §4, ADR 12) — `MarketDataPort → Alpaca`. Owns only stock-data-API +calls; the sibling `AlpacaCalendarAdapter` owns the trading-calendar API. """ from __future__ import annotations @@ -24,9 +21,8 @@ class AlpacaMarketDataAdapter: - """`get_close` reports exactly what Alpaca said, honestly (`MarketDataPort`'s own contract) — - an empty bar set means the provider has no close for this symbol/date yet, returned as `None`, - never guessed at or backfilled from an adjacent day.""" + """`get_close` reports exactly what Alpaca said — an empty bar set returns `None`, never + backfilled from an adjacent day.""" def __init__(self, *, api_key_id: str, api_secret_key: str, sandbox: bool = False) -> None: self._client = StockHistoricalDataClient( @@ -46,9 +42,7 @@ def get_close(self, *, symbol: str, market_date: date) -> CloseQuote | None: bars = bar_set.data.get(symbol, []) if not bars: return None - # One calendar day requested at daily granularity yields at most one bar; the last one is - # the closing bar if Alpaca ever returned more than one for the window. - bar = bars[-1] + bar = bars[-1] # at most one bar for the window; last one wins if more than one returned return CloseQuote( security_symbol=symbol, market_date=market_date, diff --git a/backend/app/integrations/alpaca/trade_updates_consumer.py b/backend/app/integrations/alpaca/trade_updates_consumer.py index 189dc47..6e8c404 100644 --- a/backend/app/integrations/alpaca/trade_updates_consumer.py +++ b/backend/app/integrations/alpaca/trade_updates_consumer.py @@ -1,38 +1,11 @@ """`TradeUpdatesConsumer` (S3 §6, ADR 22) — the always-on `trade_updates` websocket consumer. -No precedent elsewhere in this codebase (ADR 22's own text), so the design choices here are -S3's own, laid out explicitly rather than left implicit: - -- **Split pure logic from the network transport.** `handle_message` — validate, compute the - dedupe key, hand off to `EventIntakeService` — takes a plain `dict` and has no socket, no - `asyncio`, and no Alpaca SDK object in its signature. It is exactly what the S3 contract suite - exercises (ADR 22's consequence: "a test never opens a websocket") and exactly what - `FakeBrokerAdapter`-driven tests feed synthetic fill/reject/cancel/expired payloads into. - `run_forever` is the thin, untested-by-unit-tests wiring onto - `alpaca.trading.stream.TradingStream` — the same "adapter is thin, logic is tested separately" - split `AlpacaCalendarAdapter`/`AlpacaBrokerAdapter` already follow, just with a persistent - connection instead of a request. -- **`source_event_id`.** ADR 22 states it for fills (`execution_id`) but the `inbound_event` - table's dedupe key is `NOT NULL`, and Alpaca's `new`/`canceled`/`expired`/`rejected` events carry - no `execution_id` at all. This module derives one for those: - `f"{alpaca_order_id}:{event}:{timestamp epoch}"` — deterministic given the identical message, so - a redelivered non-fill event dedupes exactly like a redelivered fill does (generalizing FR-9's - intent beyond the fills the requirement names explicitly), without inventing a new mechanism — - it reuses `inbound_event`'s existing `UNIQUE (source, source_event_id)` constraint. -- **Which Alpaca events are tracked.** ADR 22 names `new`, `fill`, `partial_fill`, `canceled`, - `expired`, `rejected`. `new` maps to this system's own `OrderEventType.ACCEPTED` — Alpaca's own - vocabulary differs from S3 §3.2's chosen enum naming, not a different concept. `fill` and - `partial_fill` both map to `OrderEventType.FILL`: `OrderProjectionService.fold` already derives - `filled`-vs-`partially_filled` from cumulative `filled_quantity` against `quantity_requested`, so - Alpaca's own full/partial distinction would be redundant to also carry through here. Any other - Alpaca event (`pending_new`, `replaced`, ...) is intentionally ignored — logged, not inserted — - since S3's state machine has no corresponding transition for it; a garbage or malformed payload - is instead rejected by Pydantic validation before that filter is even reached, per foundation - spec §6. -- **`signature_verified = true` unconditionally** (`TrustedTransportVerifier`), per ADR 22: the - authenticated outbound TLS session Trueup itself opened to Alpaca is the trust anchor here, not a - per-message signature — stated explicitly so this source's `signature_verified` column does not - read as silently different from Stripe/Plaid's for the wrong reason. +`handle_message` is pure (no socket/asyncio) and is what the S3 contract suite exercises; +`run_forever` is the thin, untested wiring onto `alpaca.trading.stream.TradingStream`. +`source_event_id_for` derives a dedupe key for non-fill events, which carry no `execution_id`. +Only `new`/`fill`/`partial_fill`/`canceled`/`expired`/`rejected` are tracked (ADR 22); any other +event is logged and ignored. `signature_verified = true` unconditionally — the outbound TLS +session is the trust anchor, not a per-message signature (ADR 22). """ from __future__ import annotations @@ -66,9 +39,7 @@ class _AlpacaTradeUpdateOrder(BaseModel): class AlpacaTradeUpdateMessage(BaseModel): - """The validated envelope (foundation spec §6: every payload is parsed through a Pydantic - model before any service sees it) — a deliberately narrow subset of Alpaca's real - `TradeUpdate` shape, only the fields this system's own event folding needs.""" + """Validated envelope (foundation spec §6) — a narrow subset of Alpaca's `TradeUpdate` shape.""" model_config = ConfigDict(extra="ignore") @@ -81,16 +52,14 @@ class AlpacaTradeUpdateMessage(BaseModel): class TrustedTransportVerifier: - """ADR 22: the authenticated outbound TLS session to Alpaca is the trust anchor; there is no - per-message signature to check for this source.""" + """ADR 22: the outbound TLS session to Alpaca is the trust anchor; no per-message signature.""" def verify(self, *, payload: bytes, signature: str | None) -> bool: return True def source_event_id_for(message: AlpacaTradeUpdateMessage) -> str: - """ADR 7's dedupe key for a fill (`execution_id`), generalized to every event type this - module tracks (module docstring).""" + """ADR 7's dedupe key for a fill (`execution_id`), generalized to every tracked event type.""" if message.execution_id is not None: return message.execution_id return f"{message.order.id}:{message.event}:{message.timestamp.timestamp()}" @@ -101,10 +70,8 @@ def __init__(self, *, intake: EventIntakeService) -> None: self._intake = intake def handle_message(self, raw: dict[str, Any]) -> IntakeResult | None: - """Validate, dedupe-key, and hand `raw` to the shared intake path. Returns `None` for an - Alpaca event this system's state machine has no transition for (module docstring) — - distinct from `IntakeResult`, which only describes outcomes for events actually intaken. - """ + """Validate, dedupe-key, and hand `raw` to the shared intake path. `None` for an untracked + Alpaca event.""" message = AlpacaTradeUpdateMessage.model_validate(raw) if message.event not in _HANDLED_EVENTS: log.info("alpaca_trade_update_ignored", alpaca_event=message.event) @@ -129,12 +96,9 @@ def run_forever( paper: bool = True, stale_after: timedelta, ) -> None: - """The real, network-touching wiring onto `alpaca.trading.stream.TradingStream` — not - exercised by unit tests (module docstring); `handle_message` above is. Blocking: `.run()` - drives its own internal event loop. `tenacity` retries the connection with exponential - backoff; a gap since the last received message longer than `stale_after` is logged as an - operational alert rather than silently retried forever (ADR 22 — NFR-6's honest- - degradation stance).""" + """The real, network-touching wiring onto `TradingStream`; not exercised by unit tests. + Blocking. `tenacity` retries with exponential backoff; a gap past `stale_after` logs an + operational alert rather than retrying silently forever (ADR 22, NFR-6).""" import tenacity from alpaca.trading.stream import TradingStream diff --git a/backend/app/integrations/azure/keyvault_cipher.py b/backend/app/integrations/azure/keyvault_cipher.py index 50034a3..cb9de12 100644 --- a/backend/app/integrations/azure/keyvault_cipher.py +++ b/backend/app/integrations/azure/keyvault_cipher.py @@ -1,14 +1,6 @@ -"""Azure Key Vault envelope encryption (ADR 23). - -The key-encrypting key is an RSA key that never leaves the vault. Per value written, the app -generates a fresh AES-256 data key, encrypts the plaintext with it, and asks Key Vault to wrap the -data key. A stolen database dump therefore yields ciphertext and wrapped data keys and nothing -else — the database never holds a key capable of decrypting anything. - -Unwrapped data keys are cached in process, behind a short TTL. Without that cache every -`bank_link` read would make a network round trip, putting deposit and withdrawal latency and -availability directly behind Key Vault. The cache holds data keys only — never a plaintext secret -— and never reaches disk or a log. +"""Azure Key Vault envelope encryption (ADR 23). RSA key-encrypting key never leaves the vault; a +fresh AES-256 data key per value is wrapped by Key Vault, so a stolen database dump yields only +ciphertext and wrapped keys. Unwrapped data keys are cached in-process behind a short TTL. """ from __future__ import annotations @@ -37,7 +29,7 @@ class _DekCache: - """Bounded, TTL'd map of wrapped data key -> unwrapped data key.""" + """Bounded, TTL'd map of wrapped data key to unwrapped data key.""" def __init__(self, max_size: int, ttl_seconds: float) -> None: self._entries: OrderedDict[bytes, tuple[float, bytes]] = OrderedDict() diff --git a/backend/app/integrations/crypto/local_cipher.py b/backend/app/integrations/crypto/local_cipher.py index 2976d66..0fdd73f 100644 --- a/backend/app/integrations/crypto/local_cipher.py +++ b/backend/app/integrations/crypto/local_cipher.py @@ -1,13 +1,6 @@ -"""Local development and CI cipher (ADR 23). - -Implements the same `Cipher` port and the same envelope layout as `KeyVaultCipher`, differing only -in where the key-encrypting key lives: a local base64 key here, an RSA key that never leaves Azure -Key Vault there. Because the contract suite runs against both, this adapter cannot silently drift -from the one that runs in production — the standard S0 §11 sets for every port. - -This is not a fake. It performs real AES-256-GCM envelope encryption; it is simply keyed from -configuration rather than from a hardware-backed vault, which is why it is unsuitable for -production and gated on `flask_env` at startup. +"""Local development and CI cipher (ADR 23). Same `Cipher` port and envelope layout as +`KeyVaultCipher`, but keyed from local config, not a hardware-backed vault — unsuitable for +production, gated on `flask_env` at startup. """ from __future__ import annotations @@ -44,8 +37,7 @@ def __init__(self, key_b64: str) -> None: self._kek = AESGCM(key) def encrypt(self, plaintext: str) -> bytes: - # A fresh data key per value, so two customers holding the same token never produce the - # same ciphertext, and so rotating the KEK only requires re-wrapping small keys. + # Fresh data key per value: no two ciphertexts match, KEK rotation only re-wraps small keys. dek = os.urandom(DEK_BYTES) nonce = os.urandom(NONCE_BYTES) ciphertext = AESGCM(dek).encrypt(nonce, plaintext.encode("utf-8"), None) @@ -65,7 +57,6 @@ def decrypt(self, envelope: bytes) -> str: dek = self._kek.decrypt(wrap_nonce, wrapped, None) plaintext = AESGCM(dek).decrypt(nonce, ciphertext, None) except InvalidTag as exc: - # Authentication failed: wrong key, tampered bytes, or a truncated value. The caller - # is told only that the value is unreadable — see DecryptionError's docstring. + # Authentication failed: wrong key, tampered bytes, or truncated value. raise DecryptionError("stored value could not be decrypted") from exc return plaintext.decode("utf-8") diff --git a/backend/app/integrations/fake/custodian_file_adapter.py b/backend/app/integrations/fake/custodian_file_adapter.py index 1fbf1e8..a935268 100644 --- a/backend/app/integrations/fake/custodian_file_adapter.py +++ b/backend/app/integrations/fake/custodian_file_adapter.py @@ -1,21 +1,10 @@ """`CustodianFileSimulatorAdapter` (S7 §9, FR-33) — the clearly-labelled custodian-file simulator. -Unlike this package's other fakes (`fake_calendar.py`/`fake_market_data.py`/`fake_broker.py`), -which are pure in-memory test doubles seeded by hand, this one is a **production-quality -simulator** the running system actually calls (FR-33 requires a real, operable simulator -capability, not only a test fixture) — so it reads Trueup's own current internal state to build -its "clean" baseline files, via the same `app.services.reconciliation.internal_state` readers -`ReconciliationService` itself uses (S7 §9: "Generates ... from Trueup's own current internal -state by default"). `app/integrations/` has no `lint-imports` contract forbidding it from reading -`app/models/` or `app/services/` directly (only the reverse direction — services depending on a -concrete adapter — is forbidden); this module is the one place in the codebase that actually needs -that latitude, since nothing about "fetch the custodian's baseline file" can be answered without a -live read of the ledger it is a snapshot of. - -`inject_tampered_position`/`inject_late_dividend` queue a mutation applied the next time -`fetch_files()` runs. `inject_corrected_price` is different in kind (S7 §9): it doesn't go through -a "file" at all, it posts directly to `daily_close` with `source='simulated'`, exactly as S4's own -`DailyValuationJob` would for a live close. +Unlike this package's other fakes, this is a production-quality simulator the running system +actually calls (FR-33): it reads Trueup's own internal state via the same +`app.services.reconciliation.internal_state` readers `ReconciliationService` uses. `inject_*` +methods queue a mutation for the next `fetch_files()`; `inject_corrected_price` instead posts +directly to `daily_close` with `source='simulated'`. """ from __future__ import annotations @@ -59,15 +48,11 @@ JournalEntryType.DIVIDEND: CustodianTransactionType.DIVIDEND, JournalEntryType.FEE_ADJUSTMENT: CustodianTransactionType.FEE, } -"""Must stay in sync with `internal_state.CUSTODIAN_OBSERVABLE_ENTRY_TYPES`'s key set (S7 §4) -- -that set says *which* entry types are custodian-observable, this says *what custodian transaction -type* each one baseline-generates as.""" +"""Must stay in sync with `internal_state.CUSTODIAN_OBSERVABLE_ENTRY_TYPES`'s key set (S7 §4).""" class CustodianFileSimulatorAdapter: - """`CustodianFilePort` implementation. No real custodian feed is contracted yet (S7 §12), so - this is the only implementation today — exactly what NFR-12 anticipates ("simulated is - fine").""" + """`CustodianFilePort` implementation. No real custodian feed is contracted yet (S7 §12).""" def __init__( self, @@ -83,14 +68,11 @@ def __init__( def inject_tampered_position( self, *, customer_id: uuid.UUID, security_id: uuid.UUID, wrong_quantity: Units ) -> None: - """FR-32's live-fire mechanism (S7 §9): overwrites one `(customer_id, security_id)` row - in the next generated `positions.csv`, so the next `run_morning_reconciliation` call must - catch exactly this one discrepancy.""" + """FR-32's live-fire mechanism (S7 §9): overwrites one row in the next `positions.csv`.""" self._tampered_positions[(customer_id, security_id)] = wrong_quantity def clear_injections(self) -> None: - """Resets every queued tamper/injection -- lets a caller (an admin endpoint, a test) run a - second clean file after a tampered one without constructing a new adapter instance.""" + """Resets every queued tamper/injection, so a caller can run a clean file afterward.""" self._tampered_positions.clear() self._late_dividends.clear() @@ -102,9 +84,8 @@ def inject_late_dividend( amount: Money, effective_date: date, ) -> None: - """Adds a transaction row with no corresponding internal entry yet (S7 §9) -- the next - `fetch_files()` call includes it, which `ReconciliationService` correctly flags as - `unmatched_custodian_transaction`: the intended behavior, not a bug (S7 §9's own note).""" + """Adds a transaction row with no corresponding internal entry yet (S7 §9); the next + `fetch_files()` includes it, correctly flagged `unmatched_custodian_transaction`.""" self._late_dividends.append( CustodianTransactionRow( custodian_transaction_id=f"simulated-dividend:{uuid.uuid4()}", @@ -120,18 +101,9 @@ def inject_late_dividend( def inject_corrected_price( self, *, security_id: uuid.UUID, market_date: date, new_close: Price ) -> None: - """S7 §9: bypasses the custodian file entirely -- posts a second confirmed `daily_close` - row for a `market_date` that already has one, `source='simulated'` (NFR-12). - - Fires S6's `RestatementService` in the same transaction (coordinated with - restatement-engineer): a corrected close isn't customer-scoped, but `restate()` is, so - this fans out to every customer currently holding `security_id` (`TaxLotRepository. - list_customers_holding`, the same source `CorporateActionService` uses for the identical - problem). `RestatementService.restate()` requires a `source_event_id` naming the - `inbound_event` that caused the correction; no producer writes one for a `daily_close` today - (`DailyValuationJob` doesn't either), so one is synthesized here, matching - `app/services/lots/_shared.py::record_inbound_event`'s exact precedent. - """ + """S7 §9: bypasses the custodian file, posts a second confirmed `daily_close` row with + `source='simulated'` (NFR-12), and fans `RestatementService.restate()` out to every + customer holding `security_id` in the same transaction.""" with self._uow_factory() as uow: event = InboundEvent( source=InboundEventSource.MARKETDATA, diff --git a/backend/app/integrations/fake/fake_bank.py b/backend/app/integrations/fake/fake_bank.py index c1bc32a..54e49b6 100644 --- a/backend/app/integrations/fake/fake_bank.py +++ b/backend/app/integrations/fake/fake_bank.py @@ -1,10 +1,7 @@ -"""`FakeBankAdapter` — the `BankPort` fake for `tests/contract/` (S2 §8) and every other test that -needs a Plaid stand-in with no network call. +"""`FakeBankAdapter` — the `BankPort` fake for `tests/contract/` (S2 §8), no network call. -The two `build_*_webhook_body` helpers are test helpers, not part of `BankPort`: they construct the -same JSON shape a real Plaid webhook delivers for the two failure modes S2 §7/§8 name explicitly -- -`ITEM_LOGIN_REQUIRED` (FR-43) and a bounced ACH return (FR-6) -- so a test can exercise -`BankLinkService`/`DepositService`'s webhook-processing path without depending on Plaid at all. +`build_*_webhook_body` helpers construct the real Plaid webhook JSON for `ITEM_LOGIN_REQUIRED` +(FR-43) and a bounced ACH return (FR-6), for testing the webhook path without Plaid. """ from __future__ import annotations @@ -60,14 +57,7 @@ def build_ach_return_webhook_body( *, plaid_item_id: str, settlement_obligation_id: str ) -> dict[str, Any]: """FR-6: a Plaid Transfer webhook reporting the ACH debit backing a deposit was returned. - - `ports.py`'s `BankPort` has no `create_transfer`/transfer-reference method -- S2 §5.2 never - describes `DepositService.initiate()` calling out to Plaid to open a transfer, only posting the - ledger entries and a `settlement_obligation` row locally. With no provider-side transfer - reference to correlate against, this payload carries our own `settlement_obligation.id` - directly as the correlation key, in place of a Plaid `transfer_id` a real transfer-creation call - would have returned. - """ + Carries our own `settlement_obligation.id` as the correlation key (no Plaid transfer_id, S2 §5.2).""" return { "webhook_type": "TRANSFER", "webhook_code": "TRANSFER_EVENTS_UPDATE", diff --git a/backend/app/integrations/fake/fake_billing.py b/backend/app/integrations/fake/fake_billing.py index 1904e5b..1e674a3 100644 --- a/backend/app/integrations/fake/fake_billing.py +++ b/backend/app/integrations/fake/fake_billing.py @@ -1,9 +1,6 @@ -"""`FakeBillingAdapter` — the `PaymentPort` fake for `tests/contract/` (S10 §9) and every other test -that needs a Stripe Billing stand-in with no network call. +"""`FakeBillingAdapter` — the `PaymentPort` fake for `tests/contract/` (S10 §9), no network call. -`build_payment_intent_webhook_body` is a test helper, not part of `PaymentPort`: it constructs the -same JSON shape a real `payment_intent.*` Stripe webhook delivers (S10 §7), matching -`fake_kyc.py`'s identical precedent for Stripe Identity. +`build_payment_intent_webhook_body` constructs a real `payment_intent.*` Stripe webhook body (S10 §7). """ from __future__ import annotations @@ -19,12 +16,8 @@ class FakeBillingAdapter: - """Implements `PaymentPort` (structural — no inheritance required). - - `decline_customers` lets a test force a specific `stripe_customer_id` to decline every charge - (S10 §5/§9's dunning-path tests), without any conditional logic threaded through the service - layer under test. - """ + """Implements `PaymentPort` (structural — no inheritance required). `decline_customers` lets a + test force a specific `stripe_customer_id` to decline every charge (S10 §5/§9).""" def __init__(self, *, decline_customers: frozenset[str] = frozenset()) -> None: self._counter = itertools.count(1) @@ -59,8 +52,7 @@ def charge( def build_payment_intent_webhook_body( *, stripe_charge_id: str, status: str ) -> dict[str, Any]: - """A Stripe Billing `payment_intent.*` event body, shaped exactly as - `stripe.Webhook.construct_event` would hand it to a real handler (S10 §7).""" + """A Stripe Billing `payment_intent.*` event body, shaped as `construct_event` would (S10 §7).""" return { "id": f"evt_fake_{uuid.uuid4().hex[:8]}", "type": f"payment_intent.{status}", diff --git a/backend/app/integrations/fake/fake_broker.py b/backend/app/integrations/fake/fake_broker.py index 6b791a1..2b6f94a 100644 --- a/backend/app/integrations/fake/fake_broker.py +++ b/backend/app/integrations/fake/fake_broker.py @@ -1,10 +1,6 @@ -"""`FakeBrokerAdapter` — an in-memory `BrokerPort` for the contract suite and unit tests. - -Per ADR 22's own consequence, this fake also emits the identical `trade_updates` event shapes a -real Alpaca websocket message would carry (`fill_message`/`accepted_message`/`rejected_message`/ -`canceled_message`/`expired_message`), so the S3 contract suite exercises -`TradeUpdatesConsumer.handle_message` end to end with no live Alpaca connection and no websocket -ever opened. +"""`FakeBrokerAdapter` — an in-memory `BrokerPort` for the contract suite and unit tests. Also +emits the same `trade_updates` event shapes Alpaca's websocket would (ADR 22), for testing +`TradeUpdatesConsumer.handle_message` with no live connection. """ from __future__ import annotations @@ -17,9 +13,8 @@ class BrokerSubmissionRejectedError(RuntimeError): - """A fake stand-in for `alpaca.common.exceptions.APIError` on a synchronously-rejected - submission (e.g. an unrecognized symbol) — configured per `client_order_id` via - `reject_on_submit`.""" + """Fake stand-in for `alpaca.common.exceptions.APIError` on a rejected submission, configured + per `client_order_id` via `reject_on_submit`.""" class FakeBrokerAdapter: diff --git a/backend/app/integrations/fake/fake_calendar.py b/backend/app/integrations/fake/fake_calendar.py index 7efc4a5..32c9dc9 100644 --- a/backend/app/integrations/fake/fake_calendar.py +++ b/backend/app/integrations/fake/fake_calendar.py @@ -11,8 +11,7 @@ class FakeCalendarAdapter: - """Trading days are seeded explicitly via `set_trading_day`; querying an unseeded date raises, - matching a real provider call for a date nobody has asked about yet rather than guessing.""" + """Trading days are seeded via `set_trading_day`; querying an unseeded date raises.""" def __init__(self) -> None: self._days: dict[date, TradingDayInfo] = {} diff --git a/backend/app/integrations/fake/fake_kyc.py b/backend/app/integrations/fake/fake_kyc.py index 7edae32..fec8290 100644 --- a/backend/app/integrations/fake/fake_kyc.py +++ b/backend/app/integrations/fake/fake_kyc.py @@ -1,10 +1,7 @@ -"""`FakeKycAdapter` — the `KycPort` fake for `tests/contract/` (S2 §8) and every other test that -needs a Stripe Identity stand-in with no network call. +"""`FakeKycAdapter` — the `KycPort` fake for `tests/contract/` (S2 §8), no network call. -`build_verification_session_webhook_body` is a test helper, not part of `KycPort`: it constructs -the same JSON shape a real `identity.verification_session.*` Stripe webhook delivers, so a test can -exercise `KycService`'s webhook-processing path (parsing + status mapping) without depending on -Stripe at all. +`build_verification_session_webhook_body` constructs a real `identity.verification_session.*` +Stripe webhook body, for testing `KycService`'s webhook path without Stripe. """ from __future__ import annotations @@ -22,6 +19,9 @@ class FakeKycAdapter: def __init__(self) -> None: self._counter = itertools.count(1) self.created_sessions: list[str] = [] + # Tests set `retrieved_statuses[provider_session_id] = "verified"` before calling + # `retrieve_verification_session` to simulate what Stripe would report live. + self.retrieved_statuses: dict[str, str] = {} def create_verification_session(self, *, customer_id: str) -> KycSessionHandle: provider_session_id = f"vs_fake_{next(self._counter)}_{uuid.uuid4().hex[:8]}" @@ -31,12 +31,15 @@ def create_verification_session(self, *, customer_id: str) -> KycSessionHandle: client_secret=f"{provider_session_id}_secret_{uuid.uuid4().hex[:8]}", ) + def retrieve_verification_session(self, *, provider_session_id: str) -> str: + return self.retrieved_statuses.get(provider_session_id, "processing") + def build_verification_session_webhook_body( *, provider_session_id: str, status: str ) -> dict[str, Any]: - """A Stripe Identity `identity.verification_session.*` event body, shaped exactly as - `stripe.Webhook.construct_event` would hand it to a real handler (S2 §4).""" + """A Stripe Identity `identity.verification_session.*` event body, shaped as `construct_event` + would (S2 §4).""" return { "id": f"evt_fake_{uuid.uuid4().hex[:8]}", "type": f"identity.verification_session.{status}", diff --git a/backend/app/integrations/fake/fake_market_data.py b/backend/app/integrations/fake/fake_market_data.py index c997b78..428b17c 100644 --- a/backend/app/integrations/fake/fake_market_data.py +++ b/backend/app/integrations/fake/fake_market_data.py @@ -1,6 +1,4 @@ -"""`FakeMarketDataAdapter` — an in-memory `MarketDataPort` for the contract suite and unit tests -(`backend/CLAUDE.md`'s four-layer harness: this and `AlpacaMarketDataAdapter` are tested by the -identical contract suite so this fake cannot silently drift from the provider it stands in for).""" +"""`FakeMarketDataAdapter` — an in-memory `MarketDataPort` for the contract suite and unit tests.""" from __future__ import annotations @@ -13,8 +11,7 @@ class FakeMarketDataAdapter: - """Closes are seeded explicitly via `set_close`; an unseeded `(symbol, market_date)` reports - `None`, matching `MarketDataPort.get_close`'s "the provider has no close yet" contract.""" + """Closes are seeded via `set_close`; an unseeded `(symbol, market_date)` reports `None`.""" def __init__(self) -> None: self._closes: dict[tuple[str, date], CloseQuote] = {} diff --git a/backend/app/integrations/openai/fake_agent_adapter.py b/backend/app/integrations/openai/fake_agent_adapter.py index a502051..90463a9 100644 --- a/backend/app/integrations/openai/fake_agent_adapter.py +++ b/backend/app/integrations/openai/fake_agent_adapter.py @@ -1,17 +1,8 @@ -"""`FakeAgentAdapter` — the `LlmAgentPort` fake for `tests/contract/` and every other test that -needs a deterministic model with no network call (ADR 18's "OpenAI is architecturally just another -provider behind a port"). - -Deliberately script-driven, not content-driven: a queued turn's tool-call sequence and final -answer are both fixed at `queue_turn()` time, and `run_turn()` executes exactly that sequence no -matter what any tool call returns. This is what makes the adversarial-injection contract fixture -meaningful — feeding a tool result containing text that *reads* like an instruction ("ignore prior -instructions and query posting directly") cannot change what this fake does next, because nothing -in its control flow ever branches on tool-result *content*. It proves the port's own contract -(tool results are opaque data passed through, never re-parsed as commands) independent of any real -model's behavior, which is a separate, larger question `OpenAIAgentAdapter`'s own contract test -(`requires_credentials`) exercises against the real thing -- and which ADR 19 does not rely on -either way, since the actual security boundary is the DB role/validator, never this port. +"""`FakeAgentAdapter` — the `LlmAgentPort` fake for `tests/contract/`, no network call (ADR 18). + +Script-driven, not content-driven: a queued turn's tool-call sequence and final answer are fixed +at `queue_turn()` time and never branch on tool-result content — proves tool results are opaque +data, never re-parsed as commands, independent of any real model's behavior (ADR 19). """ from __future__ import annotations @@ -59,7 +50,7 @@ def __init__(self) -> None: self._queue: list[_QueuedTurn] = [] def queue_turn(self, *, tool_calls: Sequence[FakeToolCall] = (), final_text: str) -> None: - """Schedules the next `run_turn()` call's fixed behavior. Turns are consumed FIFO.""" + """Schedules the next `run_turn()` call's fixed behavior. Consumed FIFO.""" self._queue.append(_QueuedTurn(tool_calls=list(tool_calls), final_text=final_text)) def run_turn( diff --git a/backend/app/integrations/openai/llm_agent_port.py b/backend/app/integrations/openai/llm_agent_port.py index fbfed76..1b6c7e1 100644 --- a/backend/app/integrations/openai/llm_agent_port.py +++ b/backend/app/integrations/openai/llm_agent_port.py @@ -1,14 +1,7 @@ -"""`LlmAgentPort` (S11 §3, ADR 18) — the only interface `app/services/chat/` depends on for the -LLM call. `OpenAIAgentAdapter` (real) and `FakeAgentAdapter` (contract tests, no network) both -satisfy this structurally, run against the identical contract suite (`tests/contract/`). - -**`ChatToolContext` is deliberately dumb.** It carries two plain callables the adapter's function -tools invoke — `get_schema`/`execute_sql` — supplied by `ChatOrchestrationService`, which is the -only code that knows about `sql_tool_validator`, the `chat_readonly` connection, or -`ChatAuditService`. The port and its adapters never import any of those; a fake test can hand the -adapter trivial stub callables with no database at all. This is the seam ADR 19's boundary sits -behind: whatever the model decides to call, it can only ever reach these two callables, and what -those callables actually do is entirely `ChatOrchestrationService`'s decision, not the agent's. +"""`LlmAgentPort` (S11 §3, ADR 18) — the only interface `app/services/chat/` depends on for the LLM +call. `ChatToolContext` carries two plain callables (`get_schema`/`execute_sql`) supplied by +`ChatOrchestrationService`; the port and its adapters never know what those callables actually do +(ADR 19's security boundary). """ from __future__ import annotations @@ -22,16 +15,14 @@ @dataclass(frozen=True, slots=True) class SqlToolOutcome: - """What `execute_sql` hands back to the tool call — never a raw exception, always one of these - four shapes (S11 §5.3's error table).""" + """What `execute_sql` hands back — never a raw exception (S11 §5.3's error table).""" status: str """One of `chat_tool_call_status`'s values: success / validator_rejected / timeout / error.""" rows: tuple[dict[str, str], ...] = () row_count: int = 0 message: str = "" - """Populated for every non-`success` status — a structured, customer-safe explanation the - agent can react to conversationally, never a raw Postgres error string (OWASP A05).""" + """Populated for every non-`success` status — customer-safe, never a raw Postgres error (OWASP A05).""" @dataclass(frozen=True, slots=True) @@ -41,15 +32,13 @@ class ChatToolContext: get_schema: Callable[[], str] execute_sql: Callable[[str], SqlToolOutcome] on_tool_call: Callable[[str, str | None, SqlToolOutcome, int], None] - """`(tool_name, sql_text, outcome, latency_ms) -> None` — called once per tool invocation, from - inside the tool function itself, so `ChatAuditService` records it exactly when it happens - (S11 §5.2 step 4), not reconstructed afterward from the stream.""" + """`(tool_name, sql_text, outcome, latency_ms) -> None`, called once per tool invocation so + `ChatAuditService` records it when it happens (S11 §5.2 step 4).""" @dataclass(frozen=True, slots=True) class ConversationTurn: - """One prior turn of history fed back to the model as context. `role` is `"user"` or - `"assistant"`, matching `chat_message.role` (S11 §3).""" + """One prior turn of history fed back to the model. `role` matches `chat_message.role` (S11 §3).""" role: str content: str @@ -76,8 +65,7 @@ class ChatCompletedEvent: @dataclass(frozen=True, slots=True) class ChatErrorEvent: - """S11 §5.3: "OpenAI API outage/timeout: SSE stream closes with an explicit error event, never - a silent hang." `message` is always customer-safe.""" + """S11 §5.3: outage/timeout closes the SSE stream with an explicit error, never a silent hang.""" message: str @@ -95,10 +83,8 @@ def run_turn( tool_context: ChatToolContext, max_tool_iterations: int, ) -> Iterator[ChatStreamEvent]: - """Runs exactly one turn: `message` plus `history` as context, bounded by - `max_tool_iterations` tool-calling round trips (S11 §5.2 step 3, NFR-16). Yields zero or - more `ChatTokenEvent`s as they stream, then exactly one terminal event — a - `ChatCompletedEvent` or a `ChatErrorEvent` — never both, and never neither.""" + """Runs one turn bounded by `max_tool_iterations` (S11 §5.2 step 3, NFR-16). Yields zero or + more `ChatTokenEvent`s, then exactly one terminal event.""" ... diff --git a/backend/app/integrations/openai/openai_agent_adapter.py b/backend/app/integrations/openai/openai_agent_adapter.py index 544e887..ab88475 100644 --- a/backend/app/integrations/openai/openai_agent_adapter.py +++ b/backend/app/integrations/openai/openai_agent_adapter.py @@ -1,21 +1,10 @@ """`OpenAIAgentAdapter` — the real `LlmAgentPort` implementation (ADR 18): OpenAI's Agent SDK, native function-tool calling, native streaming. -**Sync-to-async bridge.** `Runner.run_streamed()` starts its run as a background `asyncio` task -the moment it is called, so it must be called from inside a running event loop -- but every Flask -view in this codebase is synchronous (S0 §3), and `LlmAgentPort.run_turn()` is a plain generator so -`ChatOrchestrationService` can drive an SSE response with an ordinary `for` loop. `_run_in_thread` -below is the seam: a dedicated background thread owns the one event loop for this turn, drains -`RunResultStreaming.stream_events()` inside it, and relays each event to the calling thread through -a plain `queue.Queue` -- the same "confine async to a thread, cross back with a thread-safe queue" -shape used to bridge any async-native SDK into a sync generator, with no partial/half-drained loop -left behind once the turn ends. - -**Tool wiring.** `_get_database_schema_tool`/`_execute_read_only_sql_tool` are the two function -tools ADR 18 names. Both are thin: they call back into whatever `ChatToolContext` the orchestration -service supplied (`ctx.context`) and record the invocation via `on_tool_call` before returning -- -this module has no idea what `chat_readonly`, the validator, or the audit log are (S0 §3's -dependency rule); it only knows the two-callable shape `llm_agent_port.py` defines. +Sync-to-async bridge: `_run_in_thread` runs `Runner.run_streamed()` on a dedicated background +thread's event loop, relaying events to the sync generator via a `queue.Queue` (Flask views are +synchronous, S0 §3). `_get_database_schema_tool`/`_execute_read_only_sql_tool` are thin wrappers +around whatever `ChatToolContext` the orchestration service supplied. """ from __future__ import annotations @@ -72,11 +61,8 @@ async def _get_database_schema_tool(ctx: RunContextWrapper[ChatToolContext]) -> @function_tool(name_override="execute_read_only_sql") async def _execute_read_only_sql_tool(ctx: RunContextWrapper[ChatToolContext], sql: str) -> str: - """Executes one read-only SELECT against the curated views and returns the rows as JSON. - - `sql` must reference only the views named in `get_database_schema`'s output. A rejected or - failed query returns a JSON `{"error": ...}` body, never a raw database error string. - """ + """Executes one read-only SELECT against the curated views; a failure returns `{"error": ...}`, + never a raw database error string.""" start = time.monotonic() outcome = ctx.context.execute_sql(sql) latency_ms = int((time.monotonic() - start) * 1000) @@ -182,7 +168,7 @@ def _capture( # mypy cannot structurally match against `list[dict[str, Any]]`. result = Runner.run_streamed( agent, - input_items, # type: ignore[arg-type] + input_items, # type: ignore[arg-type] -- SDK stubs can't match list[dict[str, Any]] context=wrapped_context, max_turns=max_tool_iterations, ) @@ -198,8 +184,7 @@ def _capture( final_text = final_output if isinstance(final_output, str) else str(final_output) event_queue.put(ChatCompletedEvent(final_text=final_text, tool_calls=tuple(collected))) except Exception as exc: - # Never a raw provider error to the customer (S11 §5.3, OWASP A05) -- logged in full - # server-side; this event is the only thing that reaches the client. + # Never a raw provider error to the customer (S11 §5.3, OWASP A05). log.error("chat_agent_turn_failed", exc_info=exc) event_queue.put( ChatErrorEvent(message="the assistant is temporarily unavailable; please try again") diff --git a/backend/app/integrations/plaid/bank_adapter.py b/backend/app/integrations/plaid/bank_adapter.py index 9c27568..4cbb230 100644 --- a/backend/app/integrations/plaid/bank_adapter.py +++ b/backend/app/integrations/plaid/bank_adapter.py @@ -1,12 +1,8 @@ """`PlaidBankAdapter` (S2 §5.1, FR-4/41/42/43) — the only module that calls the Plaid API. -`services/` depends on `BankPort` (`app/integrations/ports.py`), never this class directly (S0 §3's -dependency rule). Webhook verification follows Plaid's documented JWT scheme: each webhook carries a -`Plaid-Verification` header holding a JWT signed ES256 by a key Plaid rotates, identified by the -JWT's own `kid`; the verifier fetches that key (cached, since Plaid's own guidance is to cache by -`kid` rather than call the key-fetch endpoint per webhook), verifies the signature, checks the claim -is fresh (issued within the last five minutes — replay defence), and compares the claimed body hash -against the actual raw request body. +Webhook verification follows Plaid's JWT scheme: the `Plaid-Verification` header JWT is verified +against a key cached by `kid`, checked for freshness (5-minute replay window), and matched against +the raw body hash. """ from __future__ import annotations @@ -39,9 +35,7 @@ class PlaidCredentialsNotConfiguredError(RuntimeError): def _build_client(*, client_id: str, secret: str, environment: str) -> Any: - """Returns a `plaid_api.PlaidApi` -- typed `Any` since `plaid.*` ships no type information - (`pyproject.toml`'s mypy override) and `disallow_any_unimported` forbids naming its types - directly in an annotation.""" + """Returns a `plaid_api.PlaidApi`, typed `Any` since `plaid.*` ships no type information.""" host = { "sandbox": plaid.Environment.Sandbox, "production": plaid.Environment.Production, @@ -70,9 +64,7 @@ def create_link_token(self, *, client_user_id: str) -> LinkTokenHandle: language="en", country_codes=[CountryCode("US")], user=LinkTokenCreateRequestUser(client_user_id=client_user_id), - # `auth`: bank account + routing number verification, the only Plaid product this - # platform's bank-linking flow needs (S2 §5.1 — deposits/withdrawals via ACH, not - # transaction history or balances). + # `auth`: bank account + routing number verification (S2 §5.1's only Plaid product). products=[Products("auth")], ) ) @@ -86,8 +78,8 @@ def exchange_public_token(self, *, public_token: str) -> BankLinkHandle: class PlaidSignatureVerifier: - """Implements `app.services.intake.event_intake.SignatureVerifier` for Plaid webhooks (S0 §6 - step 1). `signature` is the `Plaid-Verification` header value -- a JWT, not an HMAC digest.""" + """Implements `SignatureVerifier` for Plaid webhooks (S0 §6 step 1). `signature` is the + `Plaid-Verification` header JWT, not an HMAC digest.""" def __init__( self, diff --git a/backend/app/integrations/ports.py b/backend/app/integrations/ports.py index cfffc15..df97774 100644 --- a/backend/app/integrations/ports.py +++ b/backend/app/integrations/ports.py @@ -1,19 +1,6 @@ """Provider ports (S0 §3) — the only interfaces `app/services/` may depend on for outside-world -calls. Each `Protocol` here gets a real adapter (the actual provider) and a fake adapter (in -`integrations/fake/`), tested by the identical contract suite (`backend/CLAUDE.md`'s four-layer -harness, `tests/contract/`) so a fake cannot silently drift from the provider it stands in for. - -`services/` depends on these `Protocol`s, never a concrete adapter (S0 §3's dependency rule, -enforced by `lint-imports`) — Dependency Inversion, and what lets a test substitute a fake with no -import of a real provider SDK at all. - -Orchestrator-owned (S0 build plan §4): written once, up front, so parallel engineers building -against different ports never collide on this shared file. A port's shape may need a real -follow-up change once an engineer actually implements against it — escalate that rather than -editing this file directly, since another track may depend on the same Protocol. - -Only the ports Wave 4 (S2 funding, S3 orders, S4 valuation) needs are defined here. -`PaymentPort` (Stripe Billing, S10) is added when S10 actually needs it — no speculative ports. +calls. Each `Protocol` gets a real adapter and a fake adapter, tested by the identical contract +suite (`tests/contract/`). Orchestrator-owned — escalate rather than editing directly. """ from __future__ import annotations @@ -34,30 +21,30 @@ @dataclass(frozen=True, slots=True) class KycSessionHandle: - """What `KycPort.create_verification_session` hands back to start the customer's hosted - verification flow (S2 §6: `POST /identity/kyc-sessions` returns the client secret the - frontend renders Stripe's flow with).""" + """What `KycPort.create_verification_session` hands back to start the hosted flow (S2 §6).""" provider_session_id: str client_secret: str class KycPort(Protocol): - """The verdict itself never arrives through this port — it arrives as a webhook through the - shared `inbound_event` intake path (S2 §4), keyed on `provider_session_id`. This port only - starts a session.""" + """The verdict arrives as a webhook through `inbound_event` intake (S2 §4); this only starts a session.""" def create_verification_session(self, *, customer_id: str) -> KycSessionHandle: ... + def retrieve_verification_session(self, *, provider_session_id: str) -> str: + """The provider's current raw status string for an existing session -- the safety net for + when a verdict webhook hasn't arrived yet (or, in local dev, can't reach the app at all).""" + ... + # --- BankPort (S2 §5.1, FR-4/41/42/43 — Plaid) ------------------------------------------------ @dataclass(frozen=True, slots=True) class BankLinkHandle: - """What `BankPort.exchange_public_token` hands back after linking (S2 §3.3/§5.1). - `access_token` is encrypted at rest by the caller before it touches `bank_link` — this port - returns the plaintext value exactly once, at exchange time, per Plaid's own flow.""" + """What `BankPort.exchange_public_token` hands back after linking (S2 §3.3/§5.1). `access_token` + is plaintext exactly once, at exchange time — caller encrypts before it touches `bank_link`.""" plaid_item_id: str access_token: str @@ -65,10 +52,7 @@ class BankLinkHandle: @dataclass(frozen=True, slots=True) class LinkTokenHandle: - """What `BankPort.create_link_token` hands back to open Plaid Link client-side (frontend - structural spec's onboarding wizard) — the client SDK cannot open at all without a - server-minted `link_token`; this is the missing step before a caller ever has a - `public_token` to hand `exchange_public_token` above.""" + """What `BankPort.create_link_token` hands back to open Plaid Link client-side.""" link_token: str expiration: datetime @@ -90,8 +74,7 @@ class OrderSide(StrEnum): @dataclass(frozen=True, slots=True) class BrokerOrderHandle: - """Confirms the broker actually accepted the order (S3 §4: `submitted` only fires once this - call succeeds — an order never shows `submitted` while the broker never received it).""" + """Confirms the broker actually accepted the order (S3 §4).""" broker_order_id: str client_order_id: str @@ -106,16 +89,12 @@ def submit_order( side: OrderSide, quantity: str, ) -> BrokerOrderHandle: - """`client_order_id` is generated by the caller (S3 §3.1/§5 — deterministic, derived from - `order.id`, never regenerated on retry) and passed in, never produced by this port.""" + """`client_order_id` is generated by the caller (S3 §3.1/§5), never produced by this port.""" ... -# Fills arrive over Alpaca's `trade_updates` websocket, not a request/response call (ADR 22) — -# deliberately not modeled as a `BrokerPort` method. The always-on consumer that reads that -# stream and feeds it into `inbound_event` is its own integration module -# (`integrations/alpaca/trade_updates_consumer.py`, S3's to design) — a genuinely different shape -# than the synchronous provider calls above, not a port method to force into this Protocol. +# Fills arrive over Alpaca's `trade_updates` websocket (ADR 22), not a BrokerPort method — see +# `integrations/alpaca/trade_updates_consumer.py`. # --- MarketDataPort (S4 §4 — Alpaca market data) ----------------------------------------------- @@ -130,9 +109,7 @@ class CloseQuote: class MarketDataPort(Protocol): def get_close(self, *, symbol: str, market_date: date) -> CloseQuote | None: - """`None` means the provider has no close for this symbol/date yet — the caller (S4 - `ValuationService`) is responsible for the missing-vs-stale distinction (S4 §6), not this - port. This port reports what the provider actually said, honestly.""" + """`None` means the provider has no close yet; caller handles missing-vs-stale (S4 §6).""" ... @@ -149,16 +126,12 @@ class TradingDayInfo: class CalendarPort(Protocol): """Populates `market_calendar_cache` (S4 §3.4). Distinct from `app/core/clock.py`'s - `TradingCalendar` Protocol, which `MarketClock` queries against the *cached* data — - `CalendarPort` is the provider-facing fetch, `TradingCalendar` is the pure in-process query - interface over what's already cached. A repository-backed adapter implementing - `TradingCalendar` reads from `market_calendar_cache` this port populates; the two are - connected by that cache, not by one calling the other directly.""" + `TradingCalendar`, which queries that cache — connected via the cache, not directly.""" def get_trading_day(self, *, market_date: date) -> TradingDayInfo: ... -# --- CustodianFilePort (S7 §3/§9 — the morning custodian file, simulated in v1) ---------------- +# --- CustodianFilePort (S7 §3/§9 — the morning custodian file, simulated in v1) --------------- class CustodianTransactionType(StrEnum): @@ -171,8 +144,7 @@ class CustodianTransactionType(StrEnum): @dataclass(frozen=True, slots=True) class CustodianPositionRow: - """`positions.csv` (S7 §3.1) — one row per `(customer_id, security_id)` the custodian - believes is held.""" + """`positions.csv` (S7 §3.1) — one row per `(customer_id, security_id)` held.""" customer_id: uuid.UUID security_id: uuid.UUID @@ -191,8 +163,7 @@ class CustodianCashRow: @dataclass(frozen=True, slots=True) class CustodianTransactionRow: - """`transactions.csv` (S7 §3.3) — one row per custodian-side transaction, keyed on the - custodian's own transaction id.""" + """`transactions.csv` (S7 §3.3) — one row per custodian-side transaction.""" custodian_transaction_id: str customer_id: uuid.UUID | None @@ -205,10 +176,8 @@ class CustodianTransactionRow: @dataclass(frozen=True, slots=True) class CustodianFileSet: - """The three files one morning run delivers (S7 §3), plus FR-33's structural - "clearly labelled" tag: `is_simulated` travels with the file set itself, not just each fake - adapter's naming convention, so `ReconciliationService` stamps it onto every - `custodian_file_row` it writes without needing to know which adapter produced the set.""" + """The three files one morning run delivers (S7 §3). `is_simulated` is FR-33's structural + "clearly labelled" tag.""" positions: list[CustodianPositionRow] cash: list[CustodianCashRow] @@ -217,21 +186,18 @@ class CustodianFileSet: class CustodianFilePort(Protocol): - """The morning custodian file source (S7 §3). No real custodian feed is contracted yet (S7 - §12) — `integrations/fake/custodian_file_adapter.py`'s simulator is the only implementation - today, exactly as NFR-12 anticipates ("simulated is fine").""" + """The morning custodian file source (S7 §3). No real custodian feed is contracted yet (S7 §12).""" def fetch_files(self, *, market_date: date) -> CustodianFileSet: ... -# --- PaymentPort (S10 §5/§7, ADR 10 — Stripe Billing) ------------------------------------------ +# --- PaymentPort (S10 §5/§7, ADR 10 — Stripe Billing) ----------------------------------------- @dataclass(frozen=True, slots=True) class PaymentMethodHandle: - """What `PaymentPort.attach_payment_method` hands back (S10 §7: `POST /payment-methods`) -- - the Stripe customer this Trueup customer now maps to (created on first call, reused - thereafter) and the payment method now attached as its default.""" + """What `PaymentPort.attach_payment_method` hands back (S10 §7): the mapped Stripe customer + and the payment method now attached as default.""" stripe_customer_id: str stripe_payment_method_id: str @@ -239,21 +205,16 @@ class PaymentMethodHandle: @dataclass(frozen=True, slots=True) class ChargeHandle: - """What a successful `PaymentPort.charge` hands back. `status` is the provider's own raw - status string (e.g. Stripe's `succeeded`) -- interpreting it into this system's own - `FeeChargeStatus` is domain policy that belongs in `FeeChargeService`, not in the port - (matching `KycService.map_verification_session_status`'s identical split).""" + """What a successful `PaymentPort.charge` hands back. `status` is the provider's raw status + string; interpreting it into `FeeChargeStatus` is `FeeChargeService`'s job, not the port's.""" stripe_charge_id: str status: str class PaymentDeclinedError(RuntimeError): - """The provider synchronously refused the charge (a card decline, insufficient funds, an - expired card, ...) -- distinct from a transport/configuration failure, which raises normally. - `FeeChargeService`/`DunningService` catch this specifically to start/continue dunning (S10 §5); - any other exception from `charge()` is an unexpected failure, not a business outcome, and is - left to propagate.""" + """The provider synchronously refused the charge — distinct from a transport/config failure. + `FeeChargeService`/`DunningService` catch this to start/continue dunning (S10 §5).""" def __init__(self, *, reason: str) -> None: super().__init__(f"payment declined: {reason}") @@ -261,12 +222,8 @@ def __init__(self, *, reason: str) -> None: class PaymentPort(Protocol): - """Stripe Billing, never Alpaca cash (ADR 10) — the only port a performance-fee charge is ever - collected through. The verdict for an *asynchronous* confirmation still arrives as a webhook - through the shared `inbound_event` intake path (S10 §7), exactly as `KycPort`'s own verdict - does; `charge()` itself is a synchronous, off-session charge against an already-attached - payment method, so its own return value/exception is the primary outcome signal, with the - webhook as a durable, idempotent confirmation of the same fact (S0 §6).""" + """Stripe Billing, never Alpaca cash (ADR 10). `charge()` is synchronous, off-session; an + async webhook confirmation also arrives via `inbound_event` intake (S10 §7).""" def attach_payment_method( self, *, stripe_customer_id: str | None, customer_email: str, payment_method_id: str @@ -280,8 +237,6 @@ def charge( amount: Money, idempotency_key: str, ) -> ChargeHandle: - """Raises `PaymentDeclinedError` on a synchronous decline; returns a `ChargeHandle` with - `status == "succeeded"` on success. `idempotency_key` must be stable across retries of the - *same* intended charge (S10 §5: `fee_charge.id`) so a retried outbox call can never produce - two provider-side charges for one `fee_charge` row.""" + """Raises `PaymentDeclinedError` on decline. `idempotency_key` must be stable across + retries (S10 §5: `fee_charge.id`) so a retried outbox call never double-charges.""" ... diff --git a/backend/app/integrations/stripe/billing_adapter.py b/backend/app/integrations/stripe/billing_adapter.py index 525ce7e..c019374 100644 --- a/backend/app/integrations/stripe/billing_adapter.py +++ b/backend/app/integrations/stripe/billing_adapter.py @@ -1,8 +1,5 @@ """`StripeBillingAdapter` (S10 §5/§7, ADR 10) — the only module that calls the Stripe Billing API. - -Follows `StripeKycAdapter`'s exact precedent: `services/` depends on `PaymentPort` -(`app/integrations/ports.py`), never this class directly (S0 §3's dependency rule, -`.importlinter`'s `services-use-ports-only` contract). +`services/` depends on `PaymentPort`, never this class directly (S0 §3). """ from __future__ import annotations @@ -23,11 +20,7 @@ class StripeCredentialsNotConfiguredError(RuntimeError): def _to_cents(amount: Money) -> int: - """Stripe's Payment Intents API takes the smallest currency unit (cents for USD), never a - decimal dollar amount -- `Money` (`NUMERIC(18,4)`) is deliberately unwrapped only here, at the - one boundary a provider's own integer-cents contract requires it (ADR 16's same reasoning as - `order.average_fill_price`), through `Money`'s public `str()` rather than its private - `Decimal`, so this stays outside `app/core/` without reaching into `Money`'s internals.""" + """Stripe takes integer cents, never a decimal amount; unwraps `Money` via its public `str()`.""" cents = (Decimal(str(amount)) * 100).quantize(Decimal("1"), rounding=ROUND_HALF_EVEN) return int(cents) @@ -49,12 +42,8 @@ def attach_payment_method( email=customer_email, api_key=self._api_key ).id - # Stripe's fixed test-mode tokens (`pm_card_visa` etc., docs.stripe.com/testing) are not - # themselves attachable ids -- `.attach()` materializes a *new* PaymentMethod object each - # call and returns it. The caller-supplied `payment_method_id` is only ever the right id - # to reuse for a real `pm_...` id already unique to one card; using it for the follow-up - # `Customer.modify()` call instead of the attached object's own `.id` fails Stripe's own - # "must be attached to the customer" check whenever a fixed test token was supplied. + # Stripe's fixed test tokens materialize a new PaymentMethod on `.attach()`; use its own + # `.id` below, not the caller-supplied one. attached = stripe.PaymentMethod.attach( payment_method_id, customer=customer_id, api_key=self._api_key ) @@ -92,8 +81,7 @@ def charge( class StripeBillingSignatureVerifier: - """Implements `app.services.intake.event_intake.SignatureVerifier` for Stripe Billing - webhooks (S0 §6 step 1, ADR 10).""" + """Implements `SignatureVerifier` for Stripe Billing webhooks (S0 §6 step 1, ADR 10).""" def __init__(self, *, webhook_secret: str) -> None: if not webhook_secret: diff --git a/backend/app/integrations/stripe/kyc_adapter.py b/backend/app/integrations/stripe/kyc_adapter.py index 8e91534..4cda671 100644 --- a/backend/app/integrations/stripe/kyc_adapter.py +++ b/backend/app/integrations/stripe/kyc_adapter.py @@ -1,9 +1,6 @@ """`StripeKycAdapter` (S2 §5.1, ADR 9) — the only module that calls the Stripe Identity API. - -`services/` depends on `KycPort` (`app/integrations/ports.py`), never this class directly (S0 §3's -dependency rule, `.importlinter`'s `services-use-ports-only` contract). ADR 9's verdict-status -mapping lives in `app.services.identity.kyc_service` instead of here for exactly that reason: it is -domain policy `KycService` must be able to call directly, and a service may not import this module. +`services/` depends on `KycPort`, never this class directly (S0 §3); ADR 9's verdict-status mapping +lives in `app.services.identity.kyc_service` instead. """ from __future__ import annotations @@ -41,10 +38,15 @@ def create_verification_session(self, *, customer_id: str) -> KycSessionHandle: provider_session_id=session.id, client_secret=session.client_secret ) + def retrieve_verification_session(self, *, provider_session_id: str) -> str: + session = stripe.identity.VerificationSession.retrieve( + provider_session_id, api_key=self._api_key + ) + return session.status + class StripeIdentitySignatureVerifier: - """Implements `app.services.intake.event_intake.SignatureVerifier` for Stripe Identity - webhooks (S0 §6 step 1, ADR 9).""" + """Implements `SignatureVerifier` for Stripe Identity webhooks (S0 §6 step 1, ADR 9).""" def __init__(self, *, webhook_secret: str) -> None: if not webhook_secret: diff --git a/backend/app/jobs/__init__.py b/backend/app/jobs/__init__.py index 8eb5cad..986197b 100644 --- a/backend/app/jobs/__init__.py +++ b/backend/app/jobs/__init__.py @@ -65,12 +65,7 @@ def snapshot_cross_check_sweep_command(market_date: datetime) -> None: @jobs_cli.command("morning-reconciliation") @click.option("--market-date", type=click.DateTime(formats=["%Y-%m-%d"]), required=True) def morning_reconciliation_command(market_date: datetime) -> None: - """Run `MorningReconciliationJob` (S7) through the identical interface Azure invokes. - - No real custodian feed is contracted yet (S7 §12) -- the simulator is the only - `CustodianFilePort` implementation today, exactly as NFR-12 anticipates ("simulated is fine"). - Swap in a real adapter here, with no change to the job itself, once one exists. - """ + """Run `MorningReconciliationJob` (S7). No real custodian feed yet -- uses the simulator.""" from app.core.db import DbRole from app.core.uow import SessionRole from app.integrations.fake.custodian_file_adapter import CustodianFileSimulatorAdapter @@ -151,28 +146,8 @@ def _fees_uow_factory() -> FeesUnitOfWork: @jobs_cli.command("outbox-worker") def outbox_worker_command() -> None: - """The always-on `job_outbox` drain process (S0 §9's "hot-path draining") -- Makefile's - `worker` target and the deployed worker Container App both invoke this exact command. Blocks - forever: `OutboxWorker.listen_forever` LISTENs for `job_outbox_ready` notifications, with a - periodic sweep on each timeout for recovery. - - Routes each of the three outbox task types this codebase produces - (`grep -rn "outbox.enqueue(" app/services/`) to its handler: - - - `submit_order_to_broker` (S3 §4) -- calls `BrokerPort.submit_order`, real Alpaca if - configured, the fake otherwise (never silently identical to production; logged loudly). - - `charge_fee` (S10 §5) -- `FeeChargeOutboxHandler`, the same one `dunning-retry` already uses. - - `process_inbound_event` (S0 §6) -- `InboundEventDispatcher`. ALPACA is the one source with - no synchronous webhook path (ADR 22: fills arrive over a websocket, not a request/response - call) -- registering its handler here is what actually lets a fill reach the ledger; before - this command existed, nothing ever called `dispatcher.register` at all, so a filled Alpaca - order updated nothing beyond Alpaca's own books. STRIPE/PLAID already apply their effect - synchronously inside the webhook controller (`stripe_billing.py`/`stripe_identity.py`/ - `plaid.py`); their own `process_inbound_event` row is a durability record, not a second - required application of the same effect -- registered here as an explicit no-op so the - dispatcher's own "a source with no handler is a wiring gap" check does not retry-then-dead- - letter every single Stripe/Plaid webhook's outbox row as though it were a real failure. - """ + """Always-on `job_outbox` drain process (S0 §9); blocks forever via `listen_forever`, routing + `submit_order_to_broker`, `charge_fee`, and `process_inbound_event` to their handlers.""" import os import uuid from datetime import UTC diff --git a/backend/app/jobs/daily_fee_accrual.py b/backend/app/jobs/daily_fee_accrual.py index e895e4a..40651f4 100644 --- a/backend/app/jobs/daily_fee_accrual.py +++ b/backend/app/jobs/daily_fee_accrual.py @@ -1,16 +1,5 @@ """`DailyFeeAccrualJob` (S10 §4, `daily` cadence) — for each customer with an active model assignment, accrues that day's performance-fee gain above their high-water-mark. - -Reuses `DailyValuationJob`/`MonthlyRebalanceJob`'s documented `ScheduledJob.perform()` -argument-gap workaround (`app/jobs/daily_valuation.py`'s own module docstring): `run()` stashes -`market_date` on the instance before delegating to `super().run()`, and `perform()` opens its own -separate `UnitOfWork` for its actual writes -- one transaction for the whole run, matching every -other scheduled job in this codebase. - -**"Active model assignment" driver query, confirmed with `rebalance-engineer`** (S9's -`customer_model_assignment` table, built concurrently in this same session): one row per assigned -customer, `CustomerModelAssignmentRepository.list_all()` on `RebalanceModelsUnitOfWork` returns -every one of them, admin/worker-role, matching `MonthlyRebalanceJob`'s own identical driver query. """ from __future__ import annotations @@ -37,7 +26,7 @@ class _DailyFeeAccrualWorkUnitOfWork(FeesUnitOfWork, RebalanceModelsUnitOfWork): - """Admin/worker-role UoW for the job's own writes -- see module docstring's flagged gap.""" + """Admin/worker-role UoW for the job's own writes.""" def _default_work_uow_factory() -> _DailyFeeAccrualWorkUnitOfWork: @@ -68,7 +57,7 @@ def run(self, *, market_date: date) -> JobOutcome: return super().run(market_date=market_date) def perform(self) -> None: - if self._market_date is None: # pragma: no cover - defensive; run() always sets it first + if self._market_date is None: # pragma: no cover - defensive raise RuntimeError("DailyFeeAccrualJob.perform() called before run()") accrual_date = self._market_date settings = get_settings() diff --git a/backend/app/jobs/daily_valuation.py b/backend/app/jobs/daily_valuation.py index f11df42..91ea8cd 100644 --- a/backend/app/jobs/daily_valuation.py +++ b/backend/app/jobs/daily_valuation.py @@ -1,17 +1,5 @@ -"""`DailyValuationJob` (S4, foundation spec §13's surface map) — fetches the day's trading-calendar -status and closing prices, and records `valuation_run`'s whole-book completeness (S4 §3.2/§6). - -**A base-class gap, flagged to `main` rather than silently patched.** `ScheduledJob.perform()` -(`app/jobs/base.py`, Wave 2) takes no arguments — it gets neither the `market_date` `run()` was -called with nor the `UnitOfWork` `run()` already opened for the `JobRun` row. Every real job the -foundation spec names beyond `NoopJob` needs both, so this reads as a foundation gap rather than an -S4-specific problem to quietly work around by changing shared base-class behaviour that other waves -also build on. Pending a real fix: `run()` is overridden here to stash `market_date` on the -instance before delegating to `super().run()`, and `perform()` opens its **own** separate -`UnitOfWork` for its actual writes — a second, independent commit rather than one atomic -transaction spanning both the `JobRun` row and the valuation writes. A crash between the two -commits could record `JobRun.status = completed` without `valuation_run` actually landing; that gap -is real and is called out in the message to `main` alongside this change, not hidden here. +"""`DailyValuationJob` (S4): fetches the day's trading-calendar status and closing prices, and +records `valuation_run`'s whole-book completeness (S4 §3.2/§6). """ from __future__ import annotations @@ -43,7 +31,7 @@ class _DailyValuationWorkUnitOfWork(ValuationUnitOfWork): - """Admin/worker-role UoW for the job's own writes — see module docstring's flagged gap.""" + """Admin/worker-role UoW for the job's own writes, separate from the `JobRun` transaction.""" def _default_work_uow_factory() -> _DailyValuationWorkUnitOfWork: @@ -76,7 +64,7 @@ def run(self, *, market_date: date) -> JobOutcome: return super().run(market_date=market_date) def perform(self) -> None: - if self._market_date is None: # pragma: no cover - defensive; run() always sets it first + if self._market_date is None: # pragma: no cover - defensive raise RuntimeError("DailyValuationJob.perform() called before run()") market_date = self._market_date now = datetime.now(UTC) @@ -103,7 +91,7 @@ def perform(self) -> None: confirmed = 0 for security_id in security_ids: security = uow.securities.get_by_id(security_id) - if security is None: # pragma: no cover - defensive; FK guarantees this in practice + if security is None: # pragma: no cover - defensive continue quote = self._market_data_port.get_close( symbol=security.symbol, market_date=market_date @@ -142,9 +130,7 @@ def perform(self) -> None: def _securities_with_positions( uow: _DailyValuationWorkUnitOfWork, market_date: date ) -> list[uuid.UUID]: - """Every security any customer holds a nonzero position in as of `market_date`, across - every customer (S4 §3.2's `securities_expected`) — an admin/worker-role query, deliberately - not tenant-scoped.""" + """Every security with a nonzero position as of `market_date`, across all customers.""" statement = ( select(Account.security_id, func.coalesce(func.sum(Posting.quantity_units), 0)) .join(Posting, Posting.account_id == Account.id) diff --git a/backend/app/jobs/dunning_retry.py b/backend/app/jobs/dunning_retry.py index a5b71c8..55b265e 100644 --- a/backend/app/jobs/dunning_retry.py +++ b/backend/app/jobs/dunning_retry.py @@ -1,13 +1,5 @@ -"""`DunningRetryJob` (S10 §5, `continuous` cadence, foundation spec §9) — retries every -`fee_charge` currently in `dunning_state.status = retrying` whose `next_retry_at` is due. - -Legitimately fires more than once per day as retries come due -- the `continuous` cadence carries -no daily/monthly uniqueness constraint on `job_run` for exactly that reason (`app/models/ops/ -job_run.py`'s partial unique indexes are both `WHERE cadence IN ('daily', 'monthly')` only). - -The due-rows read is its own short, read-only transaction; each retry then goes through -`FeeChargeOutboxHandler.charge_fee` -- the identical three-phase, no-I/O-in-transaction operation a -first attempt uses (S0 §5), never a fourth, retry-specific code path. +"""`DunningRetryJob` (S10 §5, `continuous` cadence) — retries every `fee_charge` in +`dunning_state.status = retrying` whose `next_retry_at` is due. """ from __future__ import annotations diff --git a/backend/app/jobs/monthly_fee_charge.py b/backend/app/jobs/monthly_fee_charge.py index 73f8d56..f0507b1 100644 --- a/backend/app/jobs/monthly_fee_charge.py +++ b/backend/app/jobs/monthly_fee_charge.py @@ -1,12 +1,5 @@ -"""`MonthlyFeeChargeJob` (S10 §5, `monthly` cadence) — for each customer with `fee_accrual` rows in -the billing period, creates the period's pending `fee_charge` (persisting intent plus an outbox row, -never calling Stripe itself -- S0 §5's no-I/O-in-transaction rule; `FeeChargeOutboxHandler` makes -the actual provider call once this job's own transaction has committed). - -**Billing period = the calendar month immediately before the day the job runs on**, matching the -standard "bill last month's activity" cadence a job scheduled for the 1st of each month implies; -S10's own spec does not pin down the exact day-of-month scheduling, only the `monthly` cadence -itself (foundation spec §9). +"""`MonthlyFeeChargeJob` (S10 §5, `monthly` cadence) — creates each customer's pending `fee_charge` +for the prior calendar month's `fee_accrual` rows; never calls Stripe directly (S0 §5). """ from __future__ import annotations @@ -29,7 +22,7 @@ class _MonthlyFeeChargeWorkUnitOfWork(FeesUnitOfWork): - """Admin/worker-role UoW for the job's own writes -- see module docstring's flagged gap.""" + """Admin/worker-role UoW for the job's own writes.""" def _default_work_uow_factory() -> _MonthlyFeeChargeWorkUnitOfWork: @@ -68,7 +61,7 @@ def run(self, *, market_date: date) -> JobOutcome: return super().run(market_date=market_date) def perform(self) -> None: - if self._market_date is None: # pragma: no cover - defensive; run() always sets it first + if self._market_date is None: # pragma: no cover - defensive raise RuntimeError("MonthlyFeeChargeJob.perform() called before run()") period_start, period_end = previous_month_bounds(self._market_date) settings = get_settings() diff --git a/backend/app/jobs/monthly_rebalance.py b/backend/app/jobs/monthly_rebalance.py index 3fc7838..ab592a2 100644 --- a/backend/app/jobs/monthly_rebalance.py +++ b/backend/app/jobs/monthly_rebalance.py @@ -1,27 +1,5 @@ -"""`MonthlyRebalanceJob` (S9 §7) — for each customer with an assigned model portfolio, evaluates -drift and submits whatever orders `RebalanceOrderService` generates, through the identical -`OrderService` path a customer's own order takes (S9 §6). - -Reuses `DailyValuationJob`/`MorningReconciliationJob`'s documented `ScheduledJob.perform()` -argument-gap workaround (`app/jobs/daily_valuation.py`'s own module docstring): `run()` stashes -`market_date` on the instance before delegating to `super().run()`, and `perform()` opens its own -separate `UnitOfWork` for its actual writes. - -**One transaction for the whole run, matching the existing job precedent exactly** (both -`DailyValuationJob` and `MorningReconciliationJob` do all of their work in one `UnitOfWork`, one -commit) rather than one transaction per customer -- consistency with the only precedent this -codebase has for a scheduled job's transaction shape, not a new pattern invented here. Within that -one transaction, a customer found ineligible at order-creation time (`CustomerNotEligibleError` -- -suspended between assignment and this run, S3 §7 case 2's re-check applied here) is logged and -skipped, not allowed to abort every other customer's rebalance in the same run; any other, -unexpected exception is not caught here and propagates to `ScheduledJob.run()`'s own handler, -which records the whole `job_run` as `failed` -- a genuine bug should fail loudly, an expected -per-customer ineligibility should not take the rest of the run down with it. - -`market_date` is used directly as the valuation "as of" date (matching -`ValuationService.value_book`'s own `as_of_date` contract) -- S9's monthly cadence has no separate -notion of a settlement lag the way T+1 trade settlement does; "today's" holdings are evaluated -against "today's" model. +"""`MonthlyRebalanceJob` (S9 §7) — for each assigned customer, evaluates drift and submits +whatever orders `RebalanceOrderService` generates, via `OrderService` (S9 §6). """ from __future__ import annotations @@ -52,7 +30,7 @@ class _RebalanceWorkUnitOfWork(RebalanceUnitOfWork): - """Admin/worker-role UoW for the job's own writes -- see module docstring's flagged gap.""" + """Admin/worker-role UoW for the job's own writes.""" def _default_work_uow_factory() -> _RebalanceWorkUnitOfWork: @@ -79,7 +57,7 @@ def run(self, *, market_date: date) -> JobOutcome: return super().run(market_date=market_date) def perform(self) -> None: - if self._market_date is None: # pragma: no cover - defensive; run() always sets it first + if self._market_date is None: # pragma: no cover - defensive raise RuntimeError("MonthlyRebalanceJob.perform() called before run()") market_date = self._market_date diff --git a/backend/app/jobs/morning_reconciliation.py b/backend/app/jobs/morning_reconciliation.py index eab822a..f74a0bd 100644 --- a/backend/app/jobs/morning_reconciliation.py +++ b/backend/app/jobs/morning_reconciliation.py @@ -1,23 +1,5 @@ """`MorningReconciliationJob` (S7 §6) — fetches the day's custodian file set and runs -`ReconciliationService.run_morning_reconciliation`, under the foundation spec's `job_run` daily- -cadence contract (§9) so a missing run for a trading day is itself detectable, the same mechanism -every other daily job already relies on. - -**Reuses `DailyValuationJob`'s documented `ScheduledJob.perform()` argument-gap workaround** -(`app/jobs/daily_valuation.py`'s own module docstring) rather than inventing a second one: `run()` -stashes `market_date` on the instance before delegating to `super().run()`, and `perform()` opens -its own separate `UnitOfWork` for its actual writes — a second, independent commit rather than one -atomic transaction spanning both the `JobRun` row and the reconciliation writes. The same crash -window `daily_valuation.py`'s docstring calls out (a `JobRun.status = completed` recorded without -the work itself landing) applies here too, for the same foundation-level reason. - -Reads the trading calendar from `market_calendar_cache` only (`MarketClock`/ -`CachedTradingCalendar`, matching `app/controllers/api/valuation.py`'s and -`app/services/orders/trade_update_handler.py`'s construction) — it does not itself fetch from a -`CalendarPort`. `DailyValuationJob` already populates that cache each morning (S4 §3.4); an absent -row is a real operational gap (`MarketCalendarCacheMissError`), correctly surfaced as a `job_run` -failure rather than silently guessed at. -""" +`ReconciliationService.run_morning_reconciliation` under the daily `job_run` cadence (§9).""" from __future__ import annotations @@ -41,7 +23,7 @@ class _MorningReconciliationWorkUnitOfWork(ReconciliationUnitOfWork): - """Admin/worker-role UoW for the job's own writes — see module docstring's flagged gap.""" + """Admin/worker-role UoW for the job's own writes.""" def _default_work_uow_factory() -> _MorningReconciliationWorkUnitOfWork: @@ -74,7 +56,7 @@ def run(self, *, market_date: date) -> JobOutcome: return super().run(market_date=market_date) def perform(self) -> None: - if self._market_date is None: # pragma: no cover - defensive; run() always sets it first + if self._market_date is None: # pragma: no cover - defensive raise RuntimeError("MorningReconciliationJob.perform() called before run()") market_date = self._market_date diff --git a/backend/app/jobs/snapshot_cross_check.py b/backend/app/jobs/snapshot_cross_check.py index e86d579..31428df 100644 --- a/backend/app/jobs/snapshot_cross_check.py +++ b/backend/app/jobs/snapshot_cross_check.py @@ -1,17 +1,5 @@ -"""`SnapshotCrossCheckJob` (S6 §6/§11) — the periodic sweep half of ADR 6's tamper-detection -invariant, independent of any restatement activity (`RestatementService.restate()` already runs -`cross_check` inline for whatever periods a given correction touches; this job is the standing, -whole-book check that nothing else has drifted). - -Needs no `market_date` for its own logic (unlike `DailyValuationJob`) -- `perform()` takes none, -so no override of `run()` is needed here; the CLI/scheduler still supplies one purely to satisfy -`ScheduledJob.run()`'s interface and `job_run`'s per-day uniqueness bookkeeping (S0 §13). - -**A `cross_check` failure must be loud (S6 §9 edge case 4), never a silently-caught, logged -exception.** Every snapshot is still checked in one sweep pass (so one tamper doesn't hide -another), but if any failed, `perform()` raises after the pass completes -- `ScheduledJob.run()` -(`app/jobs/base.py`) is what turns that into `JobRun.status = FAILED` and re-raises, the same loud -operational alert every other job failure in this codebase produces. +"""`SnapshotCrossCheckJob` (S6 §6/§11) — periodic whole-book sweep half of ADR 6's tamper-detection +invariant. A `cross_check` failure must raise loudly (S6 §9 edge case 4), never be swallowed. """ from __future__ import annotations @@ -33,8 +21,7 @@ class _SnapshotCrossCheckWorkUnitOfWork(RestatementUnitOfWork): - """Admin/worker-role UoW for the sweep's own reads -- matches `DailyValuationJob`'s own - `_DailyValuationWorkUnitOfWork` precedent (`app/jobs/daily_valuation.py`).""" + """Admin/worker-role UoW for the sweep's own reads.""" def _default_work_uow_factory() -> _SnapshotCrossCheckWorkUnitOfWork: diff --git a/backend/app/mcp/__init__.py b/backend/app/mcp/__init__.py new file mode 100644 index 0000000..1c64916 --- /dev/null +++ b/backend/app/mcp/__init__.py @@ -0,0 +1,74 @@ +"""S13's MCP server (ADR 24). Entry-point layer alongside `app/controllers/`.""" + +from __future__ import annotations + +from mcp.server.mcpserver import MCPServer + +from app.mcp.read_tools import ( + get_portfolio_summary, + get_transaction_history, + list_open_reconciliation_breaks, +) +from app.mcp.write_tools import ( + propose_kyc_override, + propose_rebalance, + propose_reconciliation_break_resolution, +) + +_INSTRUCTIONS = ( + "Trueup agent surface (ADR 24, S13). Three read tools (get_portfolio_summary, " + "get_transaction_history, list_open_reconciliation_breaks) answer questions against curated, " + "read-only views. Three write tools (propose_reconciliation_break_resolution, " + "propose_kyc_override, propose_rebalance) never change state directly -- each records a " + "pending proposal that a human adviser or admin must separately review and approve before " + "anything happens. Every call requires a Bearer staff_api_token." +) + + +def build_server() -> MCPServer: + server = MCPServer(name="trueup-agent-surface", instructions=_INSTRUCTIONS) + + server.add_tool( + get_portfolio_summary, + name="get_portfolio_summary", + description="Balance, holdings, and assigned model for one customer.", + ) + server.add_tool( + get_transaction_history, + name="get_transaction_history", + description="One customer's transaction history, optionally since a given timestamp.", + ) + server.add_tool( + list_open_reconciliation_breaks, + name="list_open_reconciliation_breaks", + description="The aged queue of open reconciliation breaks, oldest first.", + ) + server.add_tool( + propose_reconciliation_break_resolution, + name="propose_reconciliation_break_resolution", + description=( + "Propose resolving a reconciliation break. Records a pending approval request; " + "never resolves the break itself." + ), + ) + server.add_tool( + propose_kyc_override, + name="propose_kyc_override", + description=( + "Propose reopening a locked customer's KYC status. Records a pending approval " + "request; never changes KYC status itself." + ), + ) + server.add_tool( + propose_rebalance, + name="propose_rebalance", + description=( + "Propose an ad-hoc drift evaluation and rebalance for one customer, ahead of the " + "monthly schedule. Records a pending approval request; never places an order itself." + ), + ) + + return server + + +__all__ = ["build_server"] diff --git a/backend/app/mcp/auth.py b/backend/app/mcp/auth.py new file mode 100644 index 0000000..1604b9a --- /dev/null +++ b/backend/app/mcp/auth.py @@ -0,0 +1,62 @@ +"""Bearer-token resolution for MCP tool calls (ADR 24, S13 §3.2/§4.1). + +Revocation is re-checked on every call, never cached (S13 §6 edge case 3). +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING + +from app.core.uow import SessionRole +from app.models.identity.staff_api_token import hash_staff_api_token +from app.services.agent_surface.uow import AgentSurfaceUnitOfWork + +if TYPE_CHECKING: + import uuid + from collections.abc import Mapping + + +class McpAuthenticationError(RuntimeError): + """No valid bearer credential; surfaces to the MCP client as a tool-call error.""" + + +@dataclass(frozen=True, slots=True) +class ResolvedStaff: + staff_id: uuid.UUID + role: SessionRole + label: str + """`agent_action_request.requesting_agent` label (ADR 24).""" + + +def _extract_bearer(headers: Mapping[str, str] | None) -> str: + if not headers: + raise McpAuthenticationError("missing Authorization header") + raw = headers.get("authorization") or headers.get("Authorization") + if not raw or not raw.lower().startswith("bearer "): + raise McpAuthenticationError("Authorization header must be a Bearer token") + token = raw[len("Bearer ") :].strip() + if not token: + raise McpAuthenticationError("empty bearer token") + return token + + +def resolve_staff(headers: Mapping[str, str] | None) -> ResolvedStaff: + """Resolve a bearer token to its staff identity via a short-lived `UnitOfWork`.""" + token = _extract_bearer(headers) + token_hash = hash_staff_api_token(token) + with AgentSurfaceUnitOfWork(customer_id=None, role=SessionRole.ADMIN) as uow: + token_row = uow.staff_api_tokens.get_by_token_hash(token_hash) + if token_row is None or token_row.revoked_at is not None: + raise McpAuthenticationError("invalid or revoked API token") + staff = uow.staff.get_by_id(token_row.staff_id) + if staff is None: + raise McpAuthenticationError("invalid or revoked API token") + return ResolvedStaff( + staff_id=staff.id, + role=SessionRole(staff.role.value), + label=f"{staff.email} ({token_row.label})", + ) + + +__all__ = ["McpAuthenticationError", "ResolvedStaff", "resolve_staff"] diff --git a/backend/app/mcp/entrypoint.py b/backend/app/mcp/entrypoint.py new file mode 100644 index 0000000..d1bc069 --- /dev/null +++ b/backend/app/mcp/entrypoint.py @@ -0,0 +1,66 @@ +"""MCP server's `main()`, run as a separate ASGI process from the WSGI Flask app (S13 §4.1, ADR 24). + +Duplicates `app/__init__.py`'s engine/cipher wiring rather than importing it, to avoid pulling +in every controller blueprint for a process that registers none. +""" + +from __future__ import annotations + +import asyncio +import logging + +from app.config import Settings, get_settings +from app.core.crypto import Cipher, set_cipher +from app.core.logging import configure_logging, get_logger +from app.extensions import init_engines +from app.integrations.crypto.local_cipher import LocalDevCipher +from app.mcp import build_server + +log = get_logger(__name__) + + +def _build_cipher(settings: Settings) -> Cipher: + """Mirrors `app/__init__.py::_build_cipher`; duplicated, not imported.""" + if settings.has_key_vault_cipher: + from app.integrations.azure.keyvault_cipher import KeyVaultCipher + + return KeyVaultCipher( + vault_url=str(settings.azure_key_vault_url), + key_name=str(settings.azure_keyvault_wrap_key_name), + ) + + if settings.is_production: + raise RuntimeError( + "AZURE_KEY_VAULT_URL and AZURE_KEYVAULT_WRAP_KEY_NAME are required in production; " + "LocalDevCipher is not an acceptable production key store (ADR 23)." + ) + if settings.local_cipher_key is None: + raise RuntimeError( + "Set LOCAL_CIPHER_KEY (base64 of 32 random bytes) for development, or configure " + "Azure Key Vault. Encrypted columns must never fall back to plaintext." + ) + return LocalDevCipher(settings.local_cipher_key.get_secret_value()) + + +def main() -> None: + settings = get_settings() + configure_logging( + json_output=settings.flask_env != "development", + level=logging.DEBUG if settings.flask_debug else logging.INFO, + ) + init_engines(settings) + set_cipher(_build_cipher(settings)) + + log.info( + "mcp_server_starting", host=settings.mcp_server_host, port=settings.mcp_server_port + ) + server = build_server() + asyncio.run( + server.run_streamable_http_async( + host=settings.mcp_server_host, port=settings.mcp_server_port + ) + ) + + +if __name__ == "__main__": + main() diff --git a/backend/app/mcp/read_tools.py b/backend/app/mcp/read_tools.py new file mode 100644 index 0000000..a14840f --- /dev/null +++ b/backend/app/mcp/read_tools.py @@ -0,0 +1,158 @@ +"""S13's three read tools (S13 §4.2, ADR 24). Thin translations to ADR 19's curated views' +existing `SELECT`s under `DbRole.CHAT` -- never an LLM-composed query or raw table. +""" + +from __future__ import annotations + +import uuid +from datetime import datetime +from typing import Any + +from mcp.server.mcpserver import ( + Context, # noqa: TC002 -- needed at runtime for schema introspection. +) +from sqlalchemy import text + +from app.core.db import DbRole +from app.core.uow import UnitOfWork +from app.mcp.auth import resolve_staff +from app.services.agent_surface.uow import AgentSurfaceUnitOfWork + +_ROW_CAP = 500 + + +def _stringify(value: object) -> str | None: + if value is None: + return None + return str(value) + + +def _parse_customer_id(customer_id: str) -> uuid.UUID: + try: + return uuid.UUID(customer_id) + except ValueError as exc: + raise ValueError(f"customer_id must be a valid UUID: {exc}") from exc + + +def _assigned_model(uow: AgentSurfaceUnitOfWork, customer_id: uuid.UUID) -> dict[str, Any] | None: + assignment = uow.customer_model_assignments.get_by_customer(customer_id) + if assignment is None: + return None + model = uow.model_portfolios.get_by_id(assignment.model_portfolio_id) + return { + "model_portfolio_id": str(assignment.model_portfolio_id), + "name": model.name if model is not None else None, + "assigned_at": assignment.assigned_at.isoformat(), + } + + +def get_portfolio_summary(customer_id: str, ctx: Context) -> dict[str, Any]: + """Balance, holdings, and assigned model for one customer (S13 §4.2).""" + staff = resolve_staff(ctx.headers) + customer_uuid = _parse_customer_id(customer_id) + + with UnitOfWork(customer_id=None, role=staff.role, db_role=DbRole.CHAT) as uow: + balance_row = uow.session.execute( + text( + "SELECT COALESCE(SUM(amount_money), 0) AS balance " + "FROM v_customer_balance WHERE customer_id = :customer_id" + ), + {"customer_id": customer_id}, + ).mappings().one() + holding_rows = uow.session.execute( + text( + "SELECT security_id, symbol, SUM(quantity_remaining) AS quantity " + "FROM v_holdings WHERE customer_id = :customer_id " + "GROUP BY security_id, symbol ORDER BY symbol LIMIT :row_cap" + ), + {"customer_id": customer_id, "row_cap": _ROW_CAP}, + ).mappings().all() + + with AgentSurfaceUnitOfWork(customer_id=None, role=staff.role) as app_uow: + assigned_model = _assigned_model(app_uow, customer_uuid) + + return { + "balance": _stringify(balance_row["balance"]), + "holdings": [ + { + "security_id": _stringify(row["security_id"]), + "symbol": row["symbol"], + "quantity": _stringify(row["quantity"]), + } + for row in holding_rows + ], + "assigned_model": assigned_model, + } + + +def get_transaction_history( + customer_id: str, ctx: Context, since: str | None = None +) -> dict[str, Any]: + """Transaction history for one customer since an ISO-8601 timestamp, newest first (S13 §4.2).""" + staff = resolve_staff(ctx.headers) + _parse_customer_id(customer_id) + + since_dt: datetime | None = None + if since is not None: + try: + since_dt = datetime.fromisoformat(since) + except ValueError as exc: + raise ValueError(f"since must be an ISO-8601 timestamp: {exc}") from exc + + with UnitOfWork(customer_id=None, role=staff.role, db_role=DbRole.CHAT) as uow: + rows = uow.session.execute( + text( + "SELECT journal_entry_id, entry_type, effective_date, recorded_at, memo, " + "amount_money, quantity_units, account_role, security_id " + "FROM v_transaction_history " + "WHERE customer_id = :customer_id " + "AND (CAST(:since AS timestamptz) IS NULL " + "OR recorded_at >= CAST(:since AS timestamptz)) " + "ORDER BY recorded_at DESC LIMIT :row_cap" + ), + { + "customer_id": customer_id, + "since": since_dt.isoformat() if since_dt is not None else None, + "row_cap": _ROW_CAP, + }, + ).mappings().all() + + return { + "transactions": [ + { + "journal_entry_id": _stringify(row["journal_entry_id"]), + "entry_type": row["entry_type"], + "effective_date": _stringify(row["effective_date"]), + "recorded_at": _stringify(row["recorded_at"]), + "memo": row["memo"], + "amount_money": _stringify(row["amount_money"]), + "quantity_units": _stringify(row["quantity_units"]), + "account_role": row["account_role"], + "security_id": _stringify(row["security_id"]), + } + for row in rows + ] + } + + +def list_open_reconciliation_breaks(ctx: Context) -> dict[str, Any]: + """Aged queue of open reconciliation breaks; adviser-scope, cross-tenant (S13 §4.2, ADR 24).""" + staff = resolve_staff(ctx.headers) + + with AgentSurfaceUnitOfWork(customer_id=None, role=staff.role) as uow: + rows = uow.reconciliation_breaks.list_open() + return { + "breaks": [ + { + "id": str(row.id), + "break_type": row.break_type.value, + "customer_id": str(row.customer_id) if row.customer_id is not None else None, + "opened_at": row.opened_at.isoformat(), + "status": row.status.value, + } + for row in rows + ] + } + + +__all__ = ["get_portfolio_summary", "get_transaction_history", "list_open_reconciliation_breaks"] diff --git a/backend/app/mcp/write_tools.py b/backend/app/mcp/write_tools.py new file mode 100644 index 0000000..50cdd39 --- /dev/null +++ b/backend/app/mcp/write_tools.py @@ -0,0 +1,101 @@ +"""S13's three write tools (S13 §4.2, ADR 24). Each validates arguments, then inserts one +`pending` `agent_action_request` row -- never touches `order`/`kyc_status`/`reconciliation_break` +directly; that happens only on human approval (`app/controllers/admin/agent_requests.py`). +""" + +from __future__ import annotations + +import uuid +from typing import Any + +from mcp.server.mcpserver import ( + Context, # noqa: TC002 -- needed at runtime for schema introspection. +) + +from app.mcp.auth import resolve_staff +from app.models.ops.agent_action_request import AgentActionType +from app.services.agent_surface.uow import AgentSurfaceUnitOfWork + + +def _parse_uuid(raw: str, *, field: str) -> uuid.UUID: + try: + return uuid.UUID(raw) + except ValueError as exc: + raise ValueError(f"{field} must be a valid UUID: {exc}") from exc + + +def _require_text(raw: str, *, field: str) -> str: + stripped = raw.strip() + if not stripped: + raise ValueError(f"{field} is required") + return raw + + +def propose_reconciliation_break_resolution( + break_id: str, resolution_note: str, ctx: Context +) -> dict[str, Any]: + """Propose a resolution for a reconciliation break (S13 §4.2).""" + staff = resolve_staff(ctx.headers) + break_uuid = _parse_uuid(break_id, field="break_id") + resolution_note = _require_text(resolution_note, field="resolution_note") + + with AgentSurfaceUnitOfWork(customer_id=None, role=staff.role) as uow: + if uow.reconciliation_breaks.get_by_id(break_uuid) is None: + raise ValueError(f"reconciliation_break {break_id} not found") + + request_id = uow.agent_action_requests.create( + action=AgentActionType.RESOLVE_BREAK, + arguments={"break_id": break_id, "resolution_note": resolution_note}, + requesting_agent=staff.label, + justification=resolution_note, + ) + uow.commit() + + return {"request_id": str(request_id), "status": "pending"} + + +def propose_kyc_override(customer_id: str, reason: str, ctx: Context) -> dict[str, Any]: + """Propose reopening a locked customer's KYC status (S13 §4.2).""" + staff = resolve_staff(ctx.headers) + customer_uuid = _parse_uuid(customer_id, field="customer_id") + reason = _require_text(reason, field="reason") + + with AgentSurfaceUnitOfWork(customer_id=None, role=staff.role) as uow: + if uow.customers.get_by_id(customer_uuid) is None: + raise ValueError(f"customer {customer_id} not found") + + request_id = uow.agent_action_requests.create( + action=AgentActionType.KYC_OVERRIDE, + arguments={"customer_id": customer_id, "reason": reason}, + requesting_agent=staff.label, + justification=reason, + ) + uow.commit() + + return {"request_id": str(request_id), "status": "pending"} + + +def propose_rebalance(customer_id: str, ctx: Context) -> dict[str, Any]: + """Propose an ad-hoc rebalance evaluation for one customer (S13 §4.2).""" + staff = resolve_staff(ctx.headers) + customer_uuid = _parse_uuid(customer_id, field="customer_id") + + with AgentSurfaceUnitOfWork(customer_id=None, role=staff.role) as uow: + if uow.customers.get_by_id(customer_uuid) is None: + raise ValueError(f"customer {customer_id} not found") + + request_id = uow.agent_action_requests.create( + action=AgentActionType.REBALANCE, + arguments={"customer_id": customer_id}, + requesting_agent=staff.label, + justification=( + f"ad-hoc rebalance evaluation requested via the MCP agent surface for " + f"customer {customer_id}" + ), + ) + uow.commit() + + return {"request_id": str(request_id), "status": "pending"} + + +__all__ = ["propose_kyc_override", "propose_rebalance", "propose_reconciliation_break_resolution"] diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py index 04ae207..ef82ea0 100644 --- a/backend/app/models/__init__.py +++ b/backend/app/models/__init__.py @@ -1,14 +1,13 @@ -"""Importing this package registers every entity on `Base.metadata` — required for Alembic -autogenerate (`alembic/env.py`) and for any `Base.metadata.create_all()`/`drop_all()` call to see -the full schema. Each import below exists for that side effect; the `as X` re-export makes the -"unused import" that would otherwise be an intent, not an oversight.""" +"""Registers every entity on `Base.metadata` for Alembic autogenerate and `create_all()`/`drop_all()`.""" from app.models.base import Base as Base from app.models.identity.customer import Customer as Customer from app.models.identity.staff import Staff as Staff +from app.models.identity.staff_api_token import StaffApiToken as StaffApiToken try: from app.models.ops.admin_audit_log import AdminAuditLog as AdminAuditLog + from app.models.ops.agent_action_request import AgentActionRequest as AgentActionRequest from app.models.ops.idempotency_key import IdempotencyKey as IdempotencyKey from app.models.ops.inbound_event import InboundEvent as InboundEvent from app.models.ops.job_outbox import JobOutbox as JobOutbox diff --git a/backend/app/models/base.py b/backend/app/models/base.py index 4f37ac6..8cf4033 100644 --- a/backend/app/models/base.py +++ b/backend/app/models/base.py @@ -1,9 +1,6 @@ """Declarative base and shared metadata for every SQLAlchemy entity. -The naming convention matters more than it looks. Without it, Postgres invents constraint names -and Alembic cannot reliably drop what it created, so `downgrade` breaks — and S0 §11 makes an -`upgrade head` → `downgrade base` round-trip a CI gate. Naming every constraint deterministically -is what makes that gate passable. +Naming convention makes constraint names deterministic for Alembic downgrades (S0 §11). """ from __future__ import annotations diff --git a/backend/app/models/chat/__init__.py b/backend/app/models/chat/__init__.py index 5281189..5ccc39f 100644 --- a/backend/app/models/chat/__init__.py +++ b/backend/app/models/chat/__init__.py @@ -1,8 +1,6 @@ -"""Chat aggregates (S11) — `chat_session`, `chat_message`, `chat_tool_call`. +"""Chat aggregates (S11): `chat_session`, `chat_message`, `chat_tool_call`. -`ChatModelsUnitOfWork` is the same thin models-layer mixin shape as `LedgerUnitOfWork`/ -`RestatementModelsUnitOfWork` (S0 §5's documented extension mechanism): a models-only `UnitOfWork` -mixin that `app.services.chat.uow.ChatUnitOfWork` composes for the real service surface. +`ChatModelsUnitOfWork` is a models-only `UnitOfWork` mixin (S0 §5's extension mechanism). """ from __future__ import annotations diff --git a/backend/app/models/chat/_enum.py b/backend/app/models/chat/_enum.py index 5a0d2a4..d1d3e1d 100644 --- a/backend/app/models/chat/_enum.py +++ b/backend/app/models/chat/_enum.py @@ -1,7 +1,6 @@ -"""Shared helper for mapping a `StrEnum` to its Postgres native enum, storing `.value` rather -than SQLAlchemy's default of `.name` -- matching `app.models.ledger._enum.enum_values`. -Duplicated locally so `app/models/chat/` has no dependency on `app/models/ledger/`, the same -reasoning `app/models/restatement/_enum.py`'s own docstring gives. +"""Maps a `StrEnum` to its Postgres native enum, storing `.value` not `.name`. + +Duplicated from `app.models.ledger._enum` so `app/models/chat/` has no ledger dependency. """ from __future__ import annotations diff --git a/backend/app/models/chat/chat_message.py b/backend/app/models/chat/chat_message.py index 604f736..b51ef45 100644 --- a/backend/app/models/chat/chat_message.py +++ b/backend/app/models/chat/chat_message.py @@ -1,23 +1,8 @@ -"""`chat_message` (S11 §3) — the conversation transcript. The final natural-language answer lands -here (role `assistant`); no second copy of financial data is ever stored outside the ledger's own -tables (S11 §3's own reasoning for why `chat_tool_call` stores SQL text and a row count, not rows). - -`customer_id` is not in S11 §3's literal column list -- denormalized from `chat_session.customer_id` -by a `BEFORE INSERT` trigger, the same shape `posting.customer_id` takes from `account` (S1 §3.3), -because RLS's tenant-isolation policy (S0 §7.3, ADR 17) needs a native column on *this* table to -filter on, and application code must never be trusted to set it correctly on every insert path. - -**Why the assistant row is not append-only.** S11 §5.2 records each `chat_tool_call` "as it -happens, not batched at the end," but `chat_tool_call.message_id` (§3) is a required FK -- a tool -call needs a message row to attach to *before* the turn's final answer exists. -`ChatOrchestrationService` therefore inserts the assistant's `chat_message` row empty at turn -start (so tool calls have something to reference and commit against independently, preserving a -partial audit trail if the turn fails), then fills in `content` with exactly one `UPDATE` once -streaming completes. -`chat_message_single_finalize`, below, is the DB-level guarantee that this happens at most once per -row -- the same "single transition" shape `settlement_obligation_single_transition` (S1 §6) uses for -`pending -> terminal`. A `user`-role message's `content` is set once, at INSERT, and never touched -again -- the trigger does not need to distinguish the two roles to enforce that. +"""`chat_message` (S11 §3) — the conversation transcript. + +`customer_id` is denormalized from `chat_session` via a `BEFORE INSERT` trigger (S0 §7.3 RLS). +Assistant rows insert empty and finalize `content` exactly once via `chat_message_single_finalize` +(S1 §6 single-transition pattern). """ from __future__ import annotations @@ -58,15 +43,13 @@ class ChatMessage(Base): session_id: Mapped[uuid.UUID] = mapped_column( UUID(as_uuid=True), ForeignKey("chat_session.id"), nullable=False ) - # Denormalized from chat_session -- see module docstring. Never set by application code; the - # trigger below always overwrites whatever the ORM sends for this column. + # Denormalized from chat_session; trigger overwrites any application-set value. customer_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), nullable=True) role: Mapped[ChatMessageRole] = mapped_column( SQLAlchemyEnum(ChatMessageRole, name="chat_message_role", values_callable=enum_values), nullable=False, ) - # Empty string at INSERT for a not-yet-finalized assistant row -- see module docstring. Never - # NULL, so `chat_message_single_finalize`'s `OLD.content <> ''` check has one shape to test. + # Empty string until finalized; never NULL. content: Mapped[str] = mapped_column(Text, nullable=False, default="", server_default="") created_at: Mapped[datetime] = mapped_column( DateTime(timezone=True), nullable=False, server_default=func.now() @@ -92,8 +75,7 @@ class ChatMessage(Base): """ ) -# --- chat_message_single_finalize: content is set at most once past its initial '' (module -# docstring) -- mirrors settlement_obligation_single_transition's shape (S1 §6). ------------------ +# chat_message_single_finalize: content is set at most once (S1 §6 pattern). _CHAT_MESSAGE_SINGLE_FINALIZE_FUNCTION = DDL( # type: ignore[no-untyped-call] """ @@ -184,8 +166,7 @@ def list_for_session(self, session_id: uuid.UUID) -> list[ChatMessage]: ) def count_for_customer_since(self, customer_id: uuid.UUID, since: datetime) -> int: - """`ChatUsageLimiter`'s daily-cap check (S11 §5.2 step 1, NFR-16) -- counts `user`-role - messages only, since an `assistant` reply is never itself a billable query.""" + """Daily-cap check for `ChatUsageLimiter` (S11 §5.2 step 1, NFR-16); counts `user`-role messages only.""" return ( self.session.query(ChatMessage) .filter( @@ -197,8 +178,7 @@ def count_for_customer_since(self, customer_id: uuid.UUID, since: datetime) -> i ) def finalize_content(self, message_id: uuid.UUID, content: str) -> None: - """The one allowed `UPDATE` -- see module docstring. Raises the DB's own exception (via - `chat_message_single_finalize`) if called twice for the same row.""" + """The one allowed `UPDATE`; raises if called twice for the same row.""" message = self.session.query(ChatMessage).filter_by(id=message_id).one() message.content = content diff --git a/backend/app/models/chat/chat_session.py b/backend/app/models/chat/chat_session.py index ba7bd61..f237825 100644 --- a/backend/app/models/chat/chat_session.py +++ b/backend/app/models/chat/chat_session.py @@ -1,8 +1,6 @@ -"""`chat_session` (S11 §3) — one conversation. `status` is the concurrency lock -`ChatOrchestrationService` acquires before running a turn (S11 §5.2 step 2): `idle -> streaming` is -a single conditional `UPDATE ... WHERE status = 'idle'`, so two concurrent turns on the same session -can never both proceed -- the loser's `UPDATE` affects zero rows, not a race decided by whichever -service instance reads `status` last. +"""`chat_session` (S11 §3) — one conversation. + +`status` is a concurrency lock: `idle -> streaming` via conditional `UPDATE` (S11 §5.2 step 2). """ from __future__ import annotations @@ -50,8 +48,7 @@ class ChatSession(Base): ) -# S0 §7.3's role-aware tenant-isolation RLS policy (ADR 17) -- native customer_id, same shape as -# `account`/`tax_lot`. +# Role-aware tenant-isolation RLS policy (S0 §7.3, ADR 17). event.listen( ChatSession.__table__, "after_create", @@ -92,22 +89,18 @@ def list_for_customer(self, customer_id: uuid.UUID) -> list[ChatSession]: ) def try_begin_turn(self, session_id: uuid.UUID) -> bool: - """Atomic `idle -> streaming`. `True` iff this call won the race (S11 §5.2 step 2) -- - a second concurrent call for the same session sees `rowcount == 0` and must reject the - turn as "still answering," never run a second agent loop against the same conversation.""" + """Atomic `idle -> streaming`; `True` iff this call won the race (S11 §5.2 step 2).""" result = self.session.execute( update(ChatSession) .where(ChatSession.id == session_id, ChatSession.status == ChatSessionStatus.IDLE) .values(status=ChatSessionStatus.STREAMING) ) - # `Session.execute()` of an `Update` is a `CursorResult` at runtime; SQLAlchemy's stubs - # type it as the more general `Result[Any]`, which has no `rowcount`. + # CursorResult at runtime; stubs type it as Result[Any], which has no rowcount. rowcount: int = result.rowcount # type: ignore[attr-defined] return rowcount == 1 def end_turn(self, session_id: uuid.UUID) -> None: - """`streaming -> idle`, unconditionally -- called once per turn, in a `finally`, so a turn - that errors mid-stream still releases the lock rather than stranding the session.""" + """`streaming -> idle`, unconditionally; called in a `finally` so errors still release the lock.""" self.session.execute( update(ChatSession) .where(ChatSession.id == session_id) diff --git a/backend/app/models/chat/chat_tool_call.py b/backend/app/models/chat/chat_tool_call.py index d9b3a51..673996c 100644 --- a/backend/app/models/chat/chat_tool_call.py +++ b/backend/app/models/chat/chat_tool_call.py @@ -1,12 +1,7 @@ -"""`chat_tool_call` (S11 §3, FR-53) — the audit trail of every tool invocation the agent makes. - -Stores the SQL text and row count, never the result rows themselves (S11 §3's own reasoning: -avoids a second full copy of financial data outside the ledger's own storage — the customer's own -data either way, and `chat_message`'s stored answer is sufficient to reconstruct "what the customer -was told"). `customer_id` is denormalized from `chat_message.customer_id` by a `BEFORE INSERT` -trigger, the same shape `chat_message.customer_id` itself takes from `chat_session` — see that -module's docstring; `ChatOrchestrationService` always has a `chat_message` row (created empty at -turn start) to attach a tool call to before the call happens. +"""`chat_tool_call` (S11 §3, FR-53) — audit trail of every tool invocation the agent makes. + +Stores SQL text and row count, never result rows. `customer_id` denormalized from `chat_message` +via `BEFORE INSERT` trigger. """ from __future__ import annotations @@ -50,7 +45,7 @@ class ChatToolCall(Base): message_id: Mapped[uuid.UUID] = mapped_column( UUID(as_uuid=True), ForeignKey("chat_message.id"), nullable=False ) - # Denormalized from chat_message -- see module docstring. Never set by application code. + # Denormalized from chat_message; never set by application code. customer_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), nullable=True) tool_name: Mapped[ChatToolName] = mapped_column( SQLAlchemyEnum(ChatToolName, name="chat_tool_name", values_callable=enum_values), diff --git a/backend/app/models/chat/curated_views.py b/backend/app/models/chat/curated_views.py index 0d0033f..e4994f8 100644 --- a/backend/app/models/chat/curated_views.py +++ b/backend/app/models/chat/curated_views.py @@ -1,41 +1,7 @@ -"""The 8 curated read-model views S11 §4.1 defines, and the one shared allow-list ADR 19 requires: -`CURATED_VIEW_NAMES` is imported by both this migration's SQL and -`app.services.chat.sql_tool_validator` (ADR 19 §4.3 point 4 — "the same allow-list ... imported by -both, so they cannot silently diverge"). - -**Why these views are owner-executed with an inline tenant predicate, not `security_invoker = -true`.** ADR 19's literal SQL sketch pairs `security_invoker = true` with a `chat_readonly` role -granted `SELECT` on the 8 views "and nothing else." Postgres's actual `security_invoker` semantics -make that combination impossible: with `security_invoker = true`, the *invoking* role's own grants -are checked against the view's underlying base relations, not the owner's (`CREATE VIEW` docs, -§security_invoker) — so `chat_readonly` would need a direct `GRANT SELECT` on `posting`, -`journal_entry`, and `tax_lot` merely for the views to execute, which both contradicts "nothing -else" and means `chat_readonly` really could `SELECT * FROM posting` directly (RLS would still -scope it, but the decisive "permission denied at the DB level" test — ADR 19 §4.3, S11 §7.2 — could -never pass). Each view below is instead owner-executed (the Postgres default — no -`security_invoker` clause) with the *same* tenant predicate every `tenant_isolation` RLS policy in -this codebase already uses, inlined directly into the view body: `current_setting('app.role', -true) IN ('adviser', 'admin') OR = NULLIF(current_setting('app.customer_id', true), -'')::uuid`. This reads the identical session-scoped GUCs `UnitOfWork` already sets for every other -customer-scoped request (S0 §7.3) — the enforcement point moves from "Postgres re-evaluates RLS as -the invoker" to "the view's own predicate evaluates the same GUCs," but the security property is -identical: `chat_readonly` has zero grants on any raw relation (satisfying FR-50's literal -requirement), and cross-tenant access is refused by the database itself, independent of the LLM, -the validator, or application code (ADR 19's one governing sentence). Escalated to `main` before -this file was written; flagged here so the reasoning travels with the code, not only the PR. - -`as_of` is not a view parameter (Postgres views cannot take one) — each view that "accepts `as_of`" -per S11 §4.1 instead exposes its own temporal column (`recorded_at`, `sale_date`, or -`publish_watermark`) directly, so a live read is an unfiltered/latest-row query and an as-published -read is an ordinary `WHERE <= :watermark` the validator already permits as plain -SQL — no parameterized function, and no new allow-listed function, needed. - -`v_holdings` is **live only**: `tax_lot` is a mutable-in-place projection (S5's own docstring), not -a bitemporal/append-only table, so there is no existing mechanism to reconstruct "holdings as of a -past date" from it — and S11 §4.1 itself is explicit that this spec "adds no new temporal logic, it -only exposes the existing mechanism through a narrower, LLM-safe surface." An as-published holdings -question is answered from `v_published_snapshot.holdings_json` instead, which already carries a -point-in-time holdings snapshot (S6 §3.1) — the system prompt directs the agent there. +"""The 8 curated read-model views (S11 §4.1) and shared allow-list (ADR 19). + +Owner-executed with an inlined tenant predicate rather than `security_invoker = true` (ADR 19 §4.3, +S11 §7.2). `v_holdings` is live-only; as-published holdings come from `v_published_snapshot`. """ from __future__ import annotations @@ -179,8 +145,7 @@ WHERE ({tenant_ps}); """ -# Static owner-authored DDL: `.format()` substitutes only the fixed column literals below, never -# request/user input -- see this module's docstring for the full tenant-predicate rationale. +# Static owner-authored DDL: `.format()` substitutes only fixed column literals, never user input. CREATE_CURATED_VIEWS_SQL = _CURATED_VIEWS_SQL_TEMPLATE.format( # nosec B608 tenant_a=_TENANT_PREDICATE.format(column="a.customer_id"), tenant_tl=_TENANT_PREDICATE.format(column="tl.customer_id"), diff --git a/backend/app/models/fees/__init__.py b/backend/app/models/fees/__init__.py index e106219..2b75ae1 100644 --- a/backend/app/models/fees/__init__.py +++ b/backend/app/models/fees/__init__.py @@ -1,9 +1,5 @@ -"""Performance-fee aggregates (S10, ADR 10) -- `high_water_mark`, `fee_accrual`, `fee_charge`, -`dunning_state`, `fee_restatement_disclosure`. - -`FeesModelsUnitOfWork` is the same shape as `RestatementModelsUnitOfWork`/ -`RebalanceModelsUnitOfWork`: a thin models-layer mixin meant to be composed by the services-layer -`FeesUnitOfWork` (`app/services/fees/uow.py`), S0 §5's documented extension mechanism. +"""Performance-fee aggregates (S10, ADR 10): `high_water_mark`, `fee_accrual`, `fee_charge`, +`dunning_state`, `fee_restatement_disclosure`. Models-only `UnitOfWork` mixin (S0 §5). """ from __future__ import annotations diff --git a/backend/app/models/fees/_enum.py b/backend/app/models/fees/_enum.py index 10d921b..7095c53 100644 --- a/backend/app/models/fees/_enum.py +++ b/backend/app/models/fees/_enum.py @@ -1,7 +1,6 @@ -"""Shared helper for mapping a `StrEnum` to its Postgres native enum, storing `.value` rather than -SQLAlchemy's default of `.name` -- matching `app.models.ledger._enum`/`app.models.orders._enum`. -Duplicated locally (rather than imported cross-domain) so `app/models/fees/` has no dependency on -another domain's `models/` package. +"""Maps a `StrEnum` to its Postgres native enum, storing `.value` not `.name`. + +Duplicated locally so `app/models/fees/` has no dependency on another domain's `models/` package. """ from __future__ import annotations diff --git a/backend/app/models/fees/dunning_state.py b/backend/app/models/fees/dunning_state.py index f579dff..128e622 100644 --- a/backend/app/models/fees/dunning_state.py +++ b/backend/app/models/fees/dunning_state.py @@ -1,9 +1,6 @@ """`dunning_state` (S10 §3.5, ADR 10) — one row per `fee_charge` currently being retried. -`customer_id` is denormalized here beyond the spec's own literal column list, following -`approval_hold`'s exact precedent (S3 §3.3, `app/models/orders/approval_hold.py`) for a table keyed -off another aggregate's id: `GET /api/v1/fees` (S10 §7) needs a customer's own dunning state -tenant-scoped, and RLS needs a native column to filter on rather than a join through `fee_charge`. +`customer_id` is denormalized (`approval_hold` precedent, S3 §3.3) so RLS can filter natively. """ from __future__ import annotations @@ -92,8 +89,7 @@ def get_by_customer(self, customer_id: uuid.UUID) -> list[DunningState]: return list(self.session.execute(statement).scalars().all()) def list_due(self, *, now: datetime) -> list[DunningState]: - """`DunningRetryJob`'s (S10 §5, `continuous` cadence) driver query -- admin/worker-role - only, unscoped across every customer currently owed a retry.""" + """`DunningRetryJob`'s driver query (S10 §5); admin/worker-role, unscoped across customers.""" statement = select(DunningState).where( DunningState.status == DunningStatus.RETRYING, DunningState.next_retry_at <= now, diff --git a/backend/app/models/fees/fee_accrual.py b/backend/app/models/fees/fee_accrual.py index 4c11bde..d38948e 100644 --- a/backend/app/models/fees/fee_accrual.py +++ b/backend/app/models/fees/fee_accrual.py @@ -1,8 +1,6 @@ """`fee_accrual` (S10 §3.3, ADR 10) — one row per customer per day, append-only. -`UNIQUE (customer_id, accrual_date)` is the idempotency key `DailyFeeAccrualJob` relies on (S10 §8 -edge case 4): a retry after the job has already fully completed for a date hits this constraint on -the second attempt, and the job treats that as "already done," never as an error. +`UNIQUE (customer_id, accrual_date)` is `DailyFeeAccrualJob`'s idempotency key (S10 §8 edge case 4). """ from __future__ import annotations @@ -34,8 +32,7 @@ class FeeAccrual(Base): UUID(as_uuid=True), ForeignKey("customer.id"), nullable=False ) accrual_date: Mapped[date] = mapped_column(Date, nullable=False) - # The day's TWR-derived dollar gain above the high-water-mark; zero when the customer is still - # below their peak (S10 §3.3) -- always populated, independent of FEE_RATE_PCT's value. + # TWR-derived dollar gain above the high-water-mark; zero below peak (S10 §3.3). gain_amount: Mapped[Money] = mapped_column(MoneyType, nullable=False) fee_amount: Mapped[Money] = mapped_column(MoneyType, nullable=False) journal_entry_id: Mapped[uuid.UUID] = mapped_column( @@ -84,8 +81,7 @@ def add_for_date(self, accrual: FeeAccrual) -> None: def list_for_period( self, customer_id: uuid.UUID, *, period_start: date, period_end: date ) -> list[FeeAccrual]: - """Every accrual row within a billing period (S10 §5: `total = sum(fee_amount for those - rows)`), inclusive of both boundaries.""" + """Every accrual row within a billing period, inclusive of both boundaries (S10 §5).""" statement = self._tenant_scoped( select(FeeAccrual).where( FeeAccrual.customer_id == customer_id, @@ -98,10 +94,7 @@ def list_for_period( def list_customers_with_accruals_in_period( self, *, period_start: date, period_end: date ) -> list[uuid.UUID]: - """`MonthlyFeeChargeJob`'s (S10 §5) "for each customer with fee_accrual rows in - billing_period" driver query -- admin/worker-role only, matching every other admin/worker - cross-customer job query in this codebase (`DailyValuationJob._securities_with_positions`, - `CustomerModelAssignmentRepository.list_all`).""" + """`MonthlyFeeChargeJob`'s driver query (S10 §5); admin/worker-role, cross-customer.""" statement = ( select(FeeAccrual.customer_id) .where( diff --git a/backend/app/models/fees/fee_charge.py b/backend/app/models/fees/fee_charge.py index b4a8fde..8ae9797 100644 --- a/backend/app/models/fees/fee_charge.py +++ b/backend/app/models/fees/fee_charge.py @@ -1,12 +1,7 @@ """`fee_charge` (S10 §3.4, ADR 10) — one row per customer per billing period. -Unlike `fee_accrual`, this row is legitimately updated in place as the charge's lifecycle -progresses (`pending -> succeeded|failed|dunning`, `stripe_charge_id`/`journal_entry_id` set on -success) -- so its repository is **not** `append_only`. The one column that must never change once -set is `as_published_watermark` (FR-47: the fee basis locks to the as-published figure at charge -time, and a later restatement must never reopen it) -- enforced by a DB-level trigger, per the -spec's own required test ("attempt an UPDATE, assert it's rejected at the DB level"), not only by -application discipline. +Not `append_only`: status/`stripe_charge_id`/`journal_entry_id` update as the lifecycle progresses. +`as_published_watermark` is immutable once set (FR-47), enforced by a DB-level trigger. """ from __future__ import annotations @@ -43,11 +38,7 @@ class FeeChargeStatus(StrEnum): class FeeCharge(Base): __tablename__ = "fee_charge" __table_args__ = ( - # F5 fix (S0 §10.1 audit): `create_pending_charge`'s own idempotency was read-then-insert - # only -- two concurrent or retried `MonthlyFeeChargeJob` runs could race between the - # `get_for_period` read and the `add`, producing two charges for the same customer and - # month. `fee_accrual` already gets this right (`uq_fee_accrual_customer_date`); this - # mirrors it as the DB-level backstop the application check alone cannot provide. + # DB-level backstop against concurrent/retried MonthlyFeeChargeJob runs double-charging (S0 §10.1 F5). UniqueConstraint( "customer_id", "billing_period_start", @@ -63,7 +54,7 @@ class FeeCharge(Base): billing_period_start: Mapped[date] = mapped_column(Date, nullable=False) billing_period_end: Mapped[date] = mapped_column(Date, nullable=False) total_accrued: Mapped[Money] = mapped_column(MoneyType, nullable=False) - # Set once at charge time (S10 §5), never updated after — see module docstring's trigger. + # Set once at charge time (S10 §5); immutable thereafter. as_published_watermark: Mapped[datetime | None] = mapped_column( DateTime(timezone=True), nullable=True ) @@ -139,11 +130,7 @@ class FeeCharge(Base): ), ) -# F12 fix (S0 §10.1 audit): `status`/`stripe_charge_id`/`journal_entry_id` legitimately update as -# a charge's lifecycle progresses (module docstring), and `as_published_watermark`'s own -# column-level immutability is already enforced by the trigger above -- but the row itself must -# never be deleted; this table had no REVOKE at all (its siblings `fee_accrual`/ -# `fee_restatement_disclosure` both do). +# Row itself must never be deleted (S0 §10.1 F12). event.listen( FeeCharge.__table__, "after_create", @@ -160,8 +147,7 @@ def get_by_id(self, charge_id: uuid.UUID) -> FeeCharge | None: return self.session.execute(statement).scalar_one_or_none() def get_by_stripe_charge_id(self, stripe_charge_id: str) -> FeeCharge | None: - """Admin/worker-role only (the webhook handler runs as `SessionRole.ADMIN`, matching - `KycService.apply_verification_verdict`'s own precedent).""" + """Admin/worker-role only; the webhook handler runs as `SessionRole.ADMIN`.""" return ( self.session.query(FeeCharge) .filter_by(stripe_charge_id=stripe_charge_id) @@ -189,10 +175,7 @@ def list_for_customer(self, customer_id: uuid.UUID) -> list[FeeCharge]: def has_succeeded_charge_for_period( self, customer_id: uuid.UUID, *, period_start: date, period_end: date ) -> FeeCharge | None: - """S10 §6: `RestatementService`'s hook -- does an already-`succeeded` charge exist for the - period a restatement just touched? Admin/worker-role query (`RestatementService` runs - under whatever role posted the correcting entry, not necessarily the affected customer's - own session).""" + """`RestatementService`'s hook (S10 §6): does a `succeeded` charge exist for the touched period?""" statement = select(FeeCharge).where( FeeCharge.customer_id == customer_id, FeeCharge.billing_period_start <= period_end, diff --git a/backend/app/models/fees/fee_restatement_disclosure.py b/backend/app/models/fees/fee_restatement_disclosure.py index da26a39..db5c8a4 100644 --- a/backend/app/models/fees/fee_restatement_disclosure.py +++ b/backend/app/models/fees/fee_restatement_disclosure.py @@ -1,10 +1,5 @@ -"""`fee_restatement_disclosure` (S10 §6, ADR 10) — flags a customer account when a restatement -lands for a period that already has a `succeeded` `fee_charge`. - -Append-only: once a disclosure is recorded, it is a durable audit fact of "we told the customer -this happened," never edited or removed. `customer_id` is denormalized (see `dunning_state`'s -identical precedent) so a customer's own session can read their disclosures via RLS without joining -through `fee_charge`. +"""`fee_restatement_disclosure` (S10 §6, ADR 10) — flags an account when a restatement lands for +a period with an already-`succeeded` `fee_charge`. Append-only; `customer_id` denormalized for RLS. """ from __future__ import annotations diff --git a/backend/app/models/fees/high_water_mark.py b/backend/app/models/fees/high_water_mark.py index a17a915..61f6173 100644 --- a/backend/app/models/fees/high_water_mark.py +++ b/backend/app/models/fees/high_water_mark.py @@ -1,15 +1,7 @@ """`high_water_mark` (S10 §3.2, ADR 10) — one row per customer, updated in place. -The **one intentional exception** to the append-only posture elsewhere in this design: a -high-water-mark is a derived summary value, not a source-of-truth economic fact. The economic -facts (each day's TWR gain, each charge) remain fully append-only in `fee_accrual`/`fee_charge`; -this row is always re-derivable from them if it were ever lost, so no `append_only` guard applies -here the way it does on `journal_entry`/`posting`. - -`peak_value` is stored in dollars but tracks the customer's **TWR-adjusted** value, never the raw -portfolio balance -- see `app.services.fees.high_water_mark_service` for the mechanism that keeps -that true (S10 §8 edge case 2, the "single most consequential correctness requirement" in this -sub-project). +The one intentional exception to append-only: derived from `fee_accrual`/`fee_charge`, re-derivable +if lost. `peak_value` tracks TWR-adjusted value, not raw balance (S10 §8 edge case 2). """ from __future__ import annotations @@ -63,9 +55,7 @@ class HighWaterMark(Base): ), ) -# F12 fix (S0 §10.1 audit): `peak_value` is updated in place by design (module docstring's "one -# intentional exception" to the append-only posture), but the row itself -- one per customer -- -# must never be deleted; losing it would silently reset a customer's high-water-mark to zero. +# Row must never be deleted; losing it resets the customer's high-water-mark to zero (S0 §10.1 F12). event.listen( HighWaterMark.__table__, "after_create", @@ -76,9 +66,7 @@ class HighWaterMark(Base): class HighWaterMarkRepository(BaseRepository[HighWaterMark]): - """Not `append_only`: `peak_value`/`updated_at` are ratcheted up in place by design (module - docstring) -- the one aggregate in this codebase where an `UPDATE` is the intended, correct - operation rather than a violation `BaseRepository` should reject.""" + """Not `append_only`: `peak_value`/`updated_at` are ratcheted up in place by design.""" def __init__(self, uow: UnitOfWork) -> None: super().__init__(uow, entity=HighWaterMark, customer_id_column=HighWaterMark.customer_id) diff --git a/backend/app/models/fees/payment_method.py b/backend/app/models/fees/payment_method.py index 5f8c462..1f6d611 100644 --- a/backend/app/models/fees/payment_method.py +++ b/backend/app/models/fees/payment_method.py @@ -1,14 +1,6 @@ """`payment_method` (S10 §7, ADR 10) — the customer's Stripe-linked payment method for fee billing. -**Not in S10 §3's literal schema list** -- that section defines the fee-lifecycle tables but never -says where "the customer's Stripe-linked payment method" (§4/§5/§7's own phrase) is actually -recorded. `POST /api/v1/payment-methods` and `MonthlyFeeChargeJob`/`DunningService` both need a -concrete place to read/write it, so this table closes that gap the same way `security`/ -`market_calendar_cache`/`sub_period_return`/`customer_cash_lock` were each added to the spec that -owns their domain before any code (`DECISION-LOG.md`, 2026-09-04 "Spec gaps closed"). One row per -customer (Stripe Elements attaches one default payment method per customer in this design; no -multi-card wallet in v1). Flagged in the fee-engineer close-out report, not edited into -`docs/specs/10-performance-fees.md` directly -- that file is not this agent's to edit. +One row per customer; closes a spec gap (`DECISION-LOG.md`, 2026-09-04 "Spec gaps closed"). """ from __future__ import annotations diff --git a/backend/app/models/identity/__init__.py b/backend/app/models/identity/__init__.py index 0f1cbb3..9572e7d 100644 --- a/backend/app/models/identity/__init__.py +++ b/backend/app/models/identity/__init__.py @@ -8,9 +8,7 @@ @runtime_checkable class AuthPrincipal(Protocol): - """Structural shape shared by `Customer` and `Staff` (S0 §7.2) — `Flask-Login`'s user loader, - session serialization, and `@requires_role` operate over this without needing to know which - table a given principal came from.""" + """Structural shape shared by `Customer` and `Staff` (S0 §7.2).""" @property def id(self) -> uuid.UUID: ... diff --git a/backend/app/models/identity/bank_link.py b/backend/app/models/identity/bank_link.py index bc23179..4aee090 100644 --- a/backend/app/models/identity/bank_link.py +++ b/backend/app/models/identity/bank_link.py @@ -1,15 +1,7 @@ """`bank_link` (S2 §3.3, FR-4/41/42/43) — the customer's linked external bank account. -**FR-42, single active link**: `UNIQUE (customer_id) WHERE status = 'active'` — a real Postgres -partial unique index (`uq_bank_link_customer_active` below), not an application-level check, so -"at most one active link per customer" holds even under a concurrent double-link attempt. Linking a -new account transitions the prior `active` row to `superseded` in the same transaction that -activates the new one (`BankLinkRepository.supersede_and_activate`) -- a `superseded` link's -already-pending obligations are untouched, since `settlement_obligation` keys off -`journal_entry_id`, never `bank_link_id`. - -`plaid_access_token` is encrypted at rest (`EncryptedText`, ADR 23) and is never logged or returned -in any API response (root `CLAUDE.md`) -- `views/funding.py`'s response schema simply omits it. +FR-42: partial unique index enforces at most one `active` link per customer at the DB level. +`plaid_access_token` is encrypted at rest (`EncryptedText`, ADR 23). """ from __future__ import annotations @@ -73,7 +65,7 @@ class BankLink(Base): ) -# RLS: role-aware tenant isolation (S0 §7.3, ADR 17), the same shape as `customer`/`account`. +# RLS: role-aware tenant isolation (S0 §7.3, ADR 17). event.listen( BankLink.__table__, "after_create", @@ -97,10 +89,7 @@ class BankLink(Base): ), ) -# DELETE is revoked -- a bank link is a regulatory-relevant record of what account funding/ -# withdrawal moved through and when, matching settlement_obligation/kyc_session's posture. UPDATE -# stays granted: `status` legitimately transitions several times over a link's life (active -> -# requires_reauth, active|requires_reauth -> superseded). +# DELETE revoked: a bank link is a regulatory-relevant record. UPDATE stays granted for status transitions. event.listen( BankLink.__table__, "after_create", @@ -132,10 +121,7 @@ def active_for_customer(self, customer_id: uuid.UUID) -> BankLink | None: return self.session.execute(statement).scalar_one_or_none() def current_for_customer(self, customer_id: uuid.UUID) -> BankLink | None: - """The customer's not-yet-`superseded` link, whether `active` or `requires_reauth` -- - what `DepositService`/`WithdrawalService` check against (S2 §5.2 step 1/§5.4): a link - needing re-authentication is still "the" link, just not currently usable, and is - distinguished from "no link exists at all" (FR-4) so each gets its own clear error.""" + """The customer's not-yet-`superseded` link, `active` or `requires_reauth` (S2 §5.2/§5.4).""" statement = self._tenant_scoped( select(BankLink).where( BankLink.customer_id == customer_id, @@ -145,9 +131,7 @@ def current_for_customer(self, customer_id: uuid.UUID) -> BankLink | None: return self.session.execute(statement).scalar_one_or_none() def supersede_and_activate(self, new_link: BankLink) -> None: - """Transitions the customer's current active/requires-reauth link (if any) to - `superseded` and stages `new_link` as the new `active` row, in the same flush -- FR-42's - "linking a new bank account supersedes the prior active link in the same transaction".""" + """Transitions the current active/requires-reauth link to `superseded` and activates `new_link` (FR-42).""" existing = ( self.session.execute( self._tenant_scoped( diff --git a/backend/app/models/identity/customer.py b/backend/app/models/identity/customer.py index 360d89d..f28fcb7 100644 --- a/backend/app/models/identity/customer.py +++ b/backend/app/models/identity/customer.py @@ -15,10 +15,7 @@ class KycStatus(StrEnum): - """Plain enum.Enum members compare False against a string literal without an explicit - `.value` — the exact bug found and fixed on `StaffRole` this wave. StrEnum everywhere, - matching every other DB-backed status column in this codebase, closes it before S2 gives - these columns their first real reader.""" + """StrEnum so members compare equal to their string literal (matches every DB-backed status column).""" pending = "pending" approved = "approved" @@ -56,14 +53,7 @@ def get_id(self) -> str: return str(self.id) -# S0 §7.3's tenant-isolation RLS policy, attached directly to the table's own DDL lifecycle rather -# than living only in the Alembic migration — so any path that creates `customer` via SQLAlchemy -# metadata (a test fixture, e.g.) gets the real policy too, with no risk of drifting from what the -# migration actually ships. `NULLIF(...)` avoids depending on Postgres evaluating this OR -# left-to-right: an adviser/admin session leaves `app.customer_id` unset (''), and NULL::uuid is -# NULL rather than an error, so `id = NULL` is simply excluded, not raised, regardless of -# evaluation order (see the migration's own comment, and ADR 17). SQLAlchemy's DDL.__init__ ships -# with no type annotations, hence the ignores below. +# S0 §7.3's tenant-isolation RLS policy (ADR 17), attached to the table's DDL lifecycle. event.listen( Customer.__table__, "after_create", diff --git a/backend/app/models/identity/kyc_session.py b/backend/app/models/identity/kyc_session.py index 43e1c19..f22abf8 100644 --- a/backend/app/models/identity/kyc_session.py +++ b/backend/app/models/identity/kyc_session.py @@ -1,13 +1,7 @@ """`kyc_session` (S2 §3.2, ADR 9) — one row per verification attempt. -Append-only **per attempt**: a resubmission opens a new row (`attempt_number` incremented), it -never edits an earlier attempt's row — matching the ledger's own append-only posture, for the same -audit reason (what a KYC review actually saw must stay reconstructable). Within a single attempt's -own row, `status` still transitions exactly once, `pending -> approved | rejected`, the moment the -provider's verdict webhook arrives — the same single-transition shape as -`settlement_obligation` (`app/models/ledger/settlement_obligation.py`): a `BEFORE UPDATE` trigger -rejects any update once the row is already terminal, so this table mutates in exactly one -controlled way, and `DELETE` is revoked outright (a KYC decision is a regulatory-relevant record). +Append-only per attempt; a resubmission opens a new row. `status` transitions exactly once, +`pending -> approved | rejected`, enforced by a `BEFORE UPDATE` trigger (S1 §6 single-transition pattern). """ from __future__ import annotations @@ -36,9 +30,7 @@ def _enum_values(enum_class: type[StrEnum]) -> list[str]: class KycSessionStatus(StrEnum): - """Mapped from Stripe Identity's own session statuses (ADR 9): - `requires_input`/`processing` -> `pending`, `verified` -> `approved`, `canceled` or - `requires_input` past `KYC_MAX_ATTEMPTS` -> `rejected`.""" + """Mapped from Stripe Identity's session statuses (ADR 9).""" PENDING = "pending" APPROVED = "approved" @@ -100,15 +92,14 @@ class KycSession(Base): ), ) -# DELETE is revoked, matching settlement_obligation's regulatory-record posture; UPDATE stays -# granted for the one-time status transition the trigger above polices. +# DELETE revoked (regulatory record); UPDATE stays granted for the one-time transition above. event.listen( KycSession.__table__, "after_create", DDL("REVOKE DELETE ON kyc_session FROM trueup_app, trueup_worker;"), # type: ignore[no-untyped-call] ) -# RLS: role-aware tenant isolation (S0 §7.3, ADR 17), the same shape as `customer`/`account`. +# RLS: role-aware tenant isolation (S0 §7.3, ADR 17). event.listen( KycSession.__table__, "after_create", diff --git a/backend/app/models/identity/repository.py b/backend/app/models/identity/repository.py index 05fcc8d..21dcc76 100644 --- a/backend/app/models/identity/repository.py +++ b/backend/app/models/identity/repository.py @@ -63,12 +63,7 @@ def get_by_id(self, customer_id: uuid.UUID) -> Customer | None: def search( self, query: str, *, limit: int, after: tuple[str, uuid.UUID] | None = None ) -> list[Customer]: - """Case-insensitive email substring match (S8 §4 row 1) -- `Customer` carries no name - field yet (`app/models/identity/customer.py`'s own schema), so email is the only match - target. Keyset-paginated on `(email, id)`, ordered the same way, so a caller resuming - from `after` sees a stable, gap-free continuation regardless of concurrent inserts. - Fetches `limit + 1` rows so `app/core/pagination.py`'s `paginate()` can derive `has_more` - for free.""" + """Case-insensitive email substring match (S8 §4 row 1); keyset-paginated on `(email, id)`.""" statement = select(Customer).where(Customer.email.ilike(f"%{query}%")) if after is not None: after_email, after_id = after @@ -84,10 +79,7 @@ def __init__(self, uow: UnitOfWork) -> None: super().__init__( uow, entity=Staff, - # `staff` carries no `customer_id` and has no RLS policy (S0 §7.2: it isn't a - # customer-scoped table) — `Staff.id` satisfies `BaseRepository`'s required column - # without being used by any tenant-scoped query (`get_by_email`/`get_by_id` below - # bypass `_tenant_scoped()` entirely, by design: a login lookup must scan every row). + # `staff` has no RLS policy (S0 §7.2); Staff.id satisfies the required column, unused by tenant scoping. customer_id_column=Staff.id, ) diff --git a/backend/app/models/identity/staff.py b/backend/app/models/identity/staff.py index ed9af8d..dfdd0a1 100644 --- a/backend/app/models/identity/staff.py +++ b/backend/app/models/identity/staff.py @@ -16,12 +16,7 @@ class StaffRole(StrEnum): - """`str`-mixed so a `Staff.role` value compares, formats, and validates (Pydantic) as a bare - string exactly like `Customer.role`'s constant `"customer"` (S0 §7.2's shared `AuthPrincipal` - contract). A plain `enum.Enum` here would make `principal.role in ("adviser", "admin")` False - everywhere it's checked (`core/security.py`, the auth controller) — silently skipping the - mandatory-MFA branch and rejecting real advisers from `@requires_role`. - """ + """StrEnum so `Staff.role` compares as a bare string, matching `AuthPrincipal` (S0 §7.2).""" adviser = "adviser" admin = "admin" diff --git a/backend/app/models/identity/staff_api_token.py b/backend/app/models/identity/staff_api_token.py new file mode 100644 index 0000000..fc74891 --- /dev/null +++ b/backend/app/models/identity/staff_api_token.py @@ -0,0 +1,88 @@ +"""`staff_api_token` (S13 §3.2, ADR 24) — scoped, long-lived MCP bearer credential. + +Only `token_hash` (SHA-256) is stored; the raw token is returned once, at issue time, and +never persisted. +""" + +from __future__ import annotations + +import hashlib +import secrets +import uuid +from datetime import ( + datetime, # noqa: TC003 -- SQLAlchemy resolves mapped annotations at import time. +) +from typing import TYPE_CHECKING + +from sqlalchemy import DateTime, String, func +from sqlalchemy.dialects.postgresql import UUID +from sqlalchemy.orm import Mapped, mapped_column + +from app.core.repository import BaseRepository +from app.models.base import Base + +if TYPE_CHECKING: + from app.core.uow import UnitOfWork + + +def generate_staff_api_token() -> str: + """256 bits of CSPRNG entropy, URL-safe (ADR 24).""" + return secrets.token_urlsafe(32) + + +def hash_staff_api_token(token: str) -> str: + """SHA-256 of the raw token; the only form ever persisted.""" + return hashlib.sha256(token.encode("utf-8")).hexdigest() + + +class StaffApiToken(Base): + __tablename__ = "staff_api_token" + + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + # No FK: predates a formal cross-schema FK convention (matches + # reconciliation_break.resolved_by). + staff_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), nullable=False, index=True) + label: Mapped[str] = mapped_column(String, nullable=False) + token_hash: Mapped[str] = mapped_column(String(64), nullable=False, unique=True) + created_at: Mapped[datetime] = mapped_column( + DateTime(timezone=True), nullable=False, server_default=func.now() + ) + revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True) + + +class StaffApiTokenRepository(BaseRepository[StaffApiToken]): + """No `customer_id_column`: staff-scoped, not customer-scoped.""" + + def __init__(self, uow: UnitOfWork) -> None: + super().__init__(uow, entity=StaffApiToken) + + def add(self, token: StaffApiToken) -> None: + self.session.add(token) + + def get_by_id(self, token_id: uuid.UUID) -> StaffApiToken | None: + return self.session.query(StaffApiToken).filter_by(id=token_id).first() + + def get_by_token_hash(self, token_hash: str) -> StaffApiToken | None: + return self.session.query(StaffApiToken).filter_by(token_hash=token_hash).first() + + def list_for_staff(self, staff_id: uuid.UUID) -> list[StaffApiToken]: + return list( + self.session.query(StaffApiToken) + .filter_by(staff_id=staff_id) + .order_by(StaffApiToken.created_at.desc()) + .all() + ) + + def revoke(self, token: StaffApiToken, *, revoked_at: datetime) -> None: + """Idempotent: revoking an already-revoked token leaves its original `revoked_at` in + place.""" + if token.revoked_at is None: + token.revoked_at = revoked_at + + +__all__ = [ + "StaffApiToken", + "StaffApiTokenRepository", + "generate_staff_api_token", + "hash_staff_api_token", +] diff --git a/backend/app/models/ledger/__init__.py b/backend/app/models/ledger/__init__.py index bd2675a..71f2bcf 100644 --- a/backend/app/models/ledger/__init__.py +++ b/backend/app/models/ledger/__init__.py @@ -17,13 +17,7 @@ class LedgerUnitOfWork(UnitOfWork): - """A `UnitOfWork` exposing the repositories S1 owns (S0 §5's documented extension mechanism). - - S5 adds `tax_lots`/`lot_consumptions`/`wash_sale_adjustments` here rather than a separate - mixin: all three tables live under `app/models/ledger/` alongside `settlement_obligation` - (itself added the same way, by a later wave than the one that first wrote this class), so any - existing consumer of `LedgerUnitOfWork` (`OrdersUnitOfWork` included) gets them for free. - """ + """`UnitOfWork` exposing the repositories S1 (and S5's tax-lot tables) owns (S0 §5).""" @cached_property def accounts(self) -> AccountRepository: diff --git a/backend/app/models/ledger/_enum.py b/backend/app/models/ledger/_enum.py index 7f13e79..d088104 100644 --- a/backend/app/models/ledger/_enum.py +++ b/backend/app/models/ledger/_enum.py @@ -1,7 +1,6 @@ -"""Shared helper for mapping a `StrEnum` to its Postgres native enum, storing `.value` rather -than SQLAlchemy's default of `.name` — matching `app.models.ops.inbound_event._enum_values`. -Duplicated locally (rather than imported cross-domain) so `app/models/ledger/` has no dependency -on `app/models/ops/`. +"""Maps a `StrEnum` to its Postgres native enum, storing `.value` not `.name`. + +Duplicated locally so `app/models/ledger/` has no dependency on `app/models/ops/`. """ from __future__ import annotations diff --git a/backend/app/models/ledger/account.py b/backend/app/models/ledger/account.py index 8650738..b836d13 100644 --- a/backend/app/models/ledger/account.py +++ b/backend/app/models/ledger/account.py @@ -1,10 +1,7 @@ """`account` (S1 §3.1) — one row per (customer, role, security) the ledger posts against. -Each account has exactly one **dimension** (`money` or `units`), determined by its `role` and -never independently settable (§3.1). `Account.create()` is the only supported constructor for -that reason: it derives `dimension` from `role` via `_ROLE_DIMENSION` so application code never -passes a `dimension` that could disagree with the role. `ck_account_role_dimension` backstops the -same rule at the database, in case a row is ever written by a path that bypasses this factory. +`dimension` is derived from `role` by `Account.create()`, never independently settable; backstopped +at the DB by a `CheckConstraint`. """ from __future__ import annotations @@ -27,10 +24,7 @@ class AccountRole(StrEnum): - """Extensible per S1 §3.1: S2 adds `customer_receivable` (FR-6, S2 §5.2 step 4 -- a bounced - deposit whose cash was already invested); S5 adds `dividend_receivable`/`realized_gain_loss` - (FR-23/FR-21, ADR 11); S10 adds the performance-fee accounts (ADR 10): `fees_accrued_payable` - (customer-scoped liability), `fee_revenue_accrued`/`fee_revenue_collected` (house).""" + """Extensible per S1 §3.1; later specs (S2, S5, S10) add roles for their own domains.""" CASH = "cash" CUSTOMER_EQUITY = "customer_equity" @@ -91,12 +85,9 @@ class Account(Base): ) id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) - # Nullable: null only for house accounts (fees_expense, dividend_income) with no owning - # customer (S1 §3.1). + # Null only for house accounts (fees_expense, dividend_income) with no owning customer (S1 §3.1). customer_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), nullable=True) - # No FK: this column predates S4's `app.models.marketdata.security.Security` and is out of - # this file's task list to retrofit (S4 §3.3's own comment). Set only for position_units/ - # position_cost roles (§3.1) -- enforced by Account.create(), not a DB constraint. + # No FK (predates Security, S4 §3.3). Set only for position_units/position_cost roles. security_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), nullable=True) role: Mapped[AccountRole] = mapped_column( SQLAlchemyEnum(AccountRole, name="account_role", values_callable=enum_values), @@ -116,8 +107,7 @@ def create( customer_id: uuid.UUID | None = None, security_id: uuid.UUID | None = None, ) -> Account: - """The only supported way to build an `Account` -- derives `dimension` from `role` so it - can never be set independently (§3.1).""" + """The only supported way to build an `Account`; derives `dimension` from `role` (§3.1).""" if role in (AccountRole.POSITION_UNITS, AccountRole.POSITION_COST) and security_id is None: raise ValueError(f"{role} accounts require a security_id") return cls( @@ -129,10 +119,8 @@ def create( ) -# S0 §7.3's role-aware tenant-isolation RLS policy (ADR 17), the same shape as `customer` -# (`app/models/identity/customer.py`). A house account (`customer_id IS NULL`) is excluded from a -# customer session's rows -- it has no owning customer to match, which is correct: a customer -# never reads a house account directly. +# Role-aware tenant-isolation RLS policy (S0 §7.3, ADR 17); house accounts are excluded from a +# customer session's rows. event.listen( Account.__table__, "after_create", diff --git a/backend/app/models/ledger/customer_cash_lock.py b/backend/app/models/ledger/customer_cash_lock.py index 13a9f57..87cbf67 100644 --- a/backend/app/models/ledger/customer_cash_lock.py +++ b/backend/app/models/ledger/customer_cash_lock.py @@ -1,10 +1,7 @@ -"""`customer_cash_lock` (S1 §3.5) — a deliberately payload-free row that exists only to be locked. +"""`customer_cash_lock` (S1 §3.5) — a payload-free row that exists only to be locked. -Every cash-consuming operation (order hold in S3, withdrawal in S2, fee charge in S10) must -acquire `SELECT ... FOR UPDATE` on this row inside the same `UnitOfWork` transaction that -evaluates a cash-policy check and writes its effect, serializing concurrent cash decisions for one -customer without blocking unrelated writes to `customer` itself (§3.5). `acquire()` is the single -supported way to take the lock, so no caller hand-writes the `FOR UPDATE` query. +Cash-consuming operations acquire `SELECT ... FOR UPDATE` on this row via `acquire()` to serialize +concurrent cash decisions for one customer (§3.5). """ from __future__ import annotations @@ -56,9 +53,7 @@ class CustomerCashLock(Base): class CustomerCashLockMissingError(RuntimeError): - """Raised when `acquire()` finds no lock row for the customer -- every customer must have one, - created alongside the customer row (§3.5); a missing row means that invariant was violated - somewhere upstream, not a normal "no lock needed" case.""" + """Raised when `acquire()` finds no lock row for the customer; every customer must have one (§3.5).""" class CustomerCashLockRepository(BaseRepository[CustomerCashLock]): @@ -73,9 +68,7 @@ def create_for_customer(self, customer_id: uuid.UUID) -> CustomerCashLock: return row def acquire(self, customer_id: uuid.UUID) -> None: - """Blocks until `SELECT ... FOR UPDATE` on this customer's lock row is granted. A - precondition for using `withdrawable`/`investable` to make a *write* decision (§3.5) -- - not required for a read-only display of those figures.""" + """Blocks until `SELECT ... FOR UPDATE` on this customer's lock row is granted (§3.5).""" statement = ( select(CustomerCashLock) .where(CustomerCashLock.customer_id == customer_id) diff --git a/backend/app/models/ledger/journal_entry.py b/backend/app/models/ledger/journal_entry.py index 0b5db34..506008c 100644 --- a/backend/app/models/ledger/journal_entry.py +++ b/backend/app/models/ledger/journal_entry.py @@ -1,14 +1,7 @@ """`journal_entry` (S1 §3.2) — the bitemporal unit of correction (ADR 1). -**Direction of `superseded_by`, resolved from two requirements that only admit one consistent -reading.** S1 §7 item 3 requires "a correction round-trip (`superseded_by` chain) leaves the -original row byte-for-byte unchanged" -- and `journal_entry` is append-only (no UPDATE grant, -`AppendOnlyViolationError` at the ORM layer), so the original row can never be mutated once -written. The only way both hold is for the **new, superseding** entry to carry -`superseded_by = ` -- never the other way around. This matches ADR -1's own wording: "A superseding posting links back to the one it corrects via `superseded_by`." -`JournalEntryRepository.is_superseded()` answers "has this entry since been corrected?" as the -reverse lookup this direction implies. +`superseded_by` is set on the new, superseding entry, pointing back at the one it corrects (ADR 1); +the original row is never mutated (S1 §7 item 3). """ from __future__ import annotations @@ -63,25 +56,19 @@ class JournalEntry(Base): recorded_at: Mapped[datetime] = mapped_column( DateTime(timezone=True), nullable=False, server_default=func.now() ) - # See module docstring: set only on the *new*, superseding entry -- never written back onto - # the entry it corrects. + # Set only on the new, superseding entry (see module docstring). superseded_by: Mapped[uuid.UUID | None] = mapped_column( UUID(as_uuid=True), ForeignKey("journal_entry.id"), nullable=True ) supersedes_reason: Mapped[str | None] = mapped_column(String, nullable=True) - # Idempotency tie-in to intake (ADR 7's pattern, reused here, S1 §3.2): every journal entry - # traces back to exactly one inbound_event, and every inbound_event produces at most one - # journal entry. + # Idempotency tie-in to intake (ADR 7's pattern). source_event_id: Mapped[uuid.UUID] = mapped_column( UUID(as_uuid=True), ForeignKey("inbound_event.id"), nullable=False, unique=True ) memo: Mapped[str | None] = mapped_column(String, nullable=True) -# Append-only enforcement (S1 §6): no UPDATE/DELETE grant for either runtime credential, a hard -# DB-level guarantee bound to this table's own DDL lifecycle -- so a test fixture that creates -# `journal_entry` via SQLAlchemy metadata (rather than only via the Alembic migration) gets the -# real revocation too, same reasoning as the RLS policies in `account.py`/`posting.py`. +# Append-only enforcement (S1 §6): no UPDATE/DELETE grant for either runtime credential. event.listen( JournalEntry.__table__, "after_create", @@ -90,12 +77,8 @@ class JournalEntry(Base): class JournalEntryRepository(BaseRepository[JournalEntry]): - """No `customer_id_column`: `journal_entry` carries no customer identity of its own (S1 - §3.2's schema has none) -- a single entry can span a customer's own accounts and a house - account (e.g. a buy's fee leg). Per-customer reads go through `posting`, which does carry the - denormalized `customer_id` (§3.3); this repository is for entry-level writes and the - correction-chain lookup only, the same shape as `InboundEventRepository`/`JobOutboxRepository` - (S0 ops-spine tables with no customer identity).""" + """No `customer_id_column`: `journal_entry` carries no customer identity (S1 §3.2). Per-customer + reads go through `posting`.""" append_only = True diff --git a/backend/app/models/ledger/lot_consumption.py b/backend/app/models/ledger/lot_consumption.py index 1939ff3..c16909a 100644 --- a/backend/app/models/ledger/lot_consumption.py +++ b/backend/app/models/ledger/lot_consumption.py @@ -1,16 +1,7 @@ -"""`lot_consumption` (S5 §3.2) — which lot(s) a sell fill drew from; a sell can span multiple lots -(FIFO exhausts the oldest before moving to the next). - -**`sale_date` is a deliberate, documented addition beyond §3.2's literal column list.** §5's own -wash-sale algorithm keys its reactive window off `lot_consumption.sale_date - 30 days` / -`+ 30 days`, but nothing else in this row (or in `order_event`, which has no effective-date concept -of its own) carries that date -- without storing it here, the reactive "does a past loss sale fall -in this new buy's window" scan (`WashSaleService.on_buy_fill`) has no way to query it. Filled in -from the same NY-anchored fill date the closing `trade_sell` journal entry's `effective_date` uses. - -Mutable like `tax_lot` (see that module's docstring): `realized_gain_loss` is amended in place when -a wash-sale adjustment disallows part of the loss (ADR 11 -- "the sale's own recognized loss -shrinks"), never re-posted as a new row. +"""`lot_consumption` (S5 §3.2) — which lot(s) a sell fill drew from; FIFO can span multiple lots. + +`sale_date` supports the wash-sale window scan (§5). Mutable like `tax_lot`: `realized_gain_loss` +is amended in place by a wash-sale adjustment (ADR 11). """ from __future__ import annotations @@ -48,14 +39,11 @@ class LotConsumption(Base): quantity_consumed: Mapped[Units] = mapped_column(UnitsType, nullable=False) realized_gain_loss: Mapped[Money] = mapped_column(MoneyType, nullable=False) is_provisional: Mapped[bool] = mapped_column(Boolean, nullable=False) - # See module docstring -- not in S5 §3.2's literal table, added to make its own §5 algorithm - # implementable. + # Not in S5 §3.2's literal table; added for the §5 wash-sale window scan. sale_date: Mapped[date] = mapped_column(Date, nullable=False) -# F12/I3 fix (S0 §10.1 audit): mutable in place (module docstring: `realized_gain_loss` is amended -# by a wash-sale adjustment, ADR 11), but must never be deleted; the S5 migration that created -# this table carried no REVOKE at all, unlike every other money-bearing table in the schema. +# Mutable in place but must never be deleted (S0 §10.1 F12/I3). event.listen( LotConsumption.__table__, "after_create", @@ -66,9 +54,7 @@ class LotConsumption(Base): class LotConsumptionRepository(BaseRepository[LotConsumption]): - """No `customer_id_column`: `lot_consumption` carries no customer identity of its own (module - docstring's schema), matching `journal_entry`/`order_event`'s precedent -- per-customer reads - join through `tax_lot`, which does carry `customer_id`.""" + """No `customer_id_column`: per-customer reads join through `tax_lot`.""" def __init__(self, uow: UnitOfWork) -> None: super().__init__(uow, entity=LotConsumption) @@ -86,10 +72,7 @@ def list_for_closing_fill(self, execution_id: str) -> list[LotConsumption]: def list_realized_in_period( self, customer_id: uuid.UUID, *, period_start: date, period_end: date ) -> list[LotConsumption]: - """Every consumption whose `sale_date` falls inside `[period_start, period_end]` -- the - tax-export's own realized-activity slice (S8 §5), joined through `tax_lot` the same way - `find_unadjusted_losses_in_window` does since this table carries no `customer_id` of its - own (module docstring).""" + """Every consumption whose `sale_date` falls inside `[period_start, period_end]` (S8 §5).""" statement = ( select(LotConsumption) .join(TaxLot, TaxLot.id == LotConsumption.tax_lot_id) @@ -103,9 +86,7 @@ def list_realized_in_period( return list(self.session.execute(statement).scalars().all()) def list_for_lots(self, tax_lot_ids: Sequence[uuid.UUID]) -> list[LotConsumption]: - """Every consumption row against any of the given lots -- `GET /api/v1/lots` (S8 §3) - aggregates a lot's realized gain and provisional status from its own consumptions - (S5 §7 edge case 1), fetched here in one query rather than N+1 per lot.""" + """Every consumption row against any of the given lots, in one query (S8 §3).""" if not tax_lot_ids: return [] statement = select(LotConsumption).where(LotConsumption.tax_lot_id.in_(tax_lot_ids)) @@ -119,10 +100,7 @@ def find_unadjusted_losses_in_window( window_start: date, window_end: date, ) -> list[LotConsumption]: - """ADR 11's reactive side: loss consumptions of `security_id`, sold inside the window a - *new* buy fill just opened, that have not already been carried into a wash-sale - adjustment (`NOT EXISTS` rather than a join, so a consumption already adjusted -- one - `wash_sale_adjustment` per `original_lot_consumption_id`, S5 §3.3 -- is never revisited).""" + """ADR 11's reactive side: loss consumptions in the window not already wash-sale-adjusted.""" already_adjusted = select(WashSaleAdjustment.id).where( WashSaleAdjustment.original_lot_consumption_id == LotConsumption.id ) diff --git a/backend/app/models/ledger/posting.py b/backend/app/models/ledger/posting.py index 50e2f86..2480957 100644 --- a/backend/app/models/ledger/posting.py +++ b/backend/app/models/ledger/posting.py @@ -1,19 +1,7 @@ """`posting` (S1 §3.3) — the legs. Each row moves exactly one dimension on exactly one account. -Two triggers, both bound to this table's own DDL lifecycle (so any path that creates `posting` -via SQLAlchemy metadata -- a test fixture included -- gets the real behaviour, never only what a -migration happens to also state): - -- `posting_before_insert` (`BEFORE INSERT`, per-row, synchronous): denormalizes `customer_id` from - the target account and validates that the non-null leg column matches the account's dimension - (§3.3). `posting.customer_id` is never written by application code -- the trigger always - overwrites it from `account.customer_id`, so what the ORM sends for that column is irrelevant. -- `ledger_balance` (`AFTER INSERT OR UPDATE OR DELETE`, `DEFERRABLE INITIALLY DEFERRED`, ADR 17): - fires once at `COMMIT`, after every leg of a multi-row posting has been written, and raises if a - journal entry's money postings do not sum to zero (§3.4). - -Both are distinct from `PostingService`'s own application-layer zero-sum check (belt-and-suspenders, -matching `BaseRepository`'s append-only guard being one layer above the revoked DB grants). +Two DB triggers: `posting_before_insert` denormalizes `customer_id` and validates dimension match; +`ledger_balance` (deferred to `COMMIT`, ADR 17) enforces each journal entry sums to zero (§3.4). """ from __future__ import annotations @@ -53,8 +41,7 @@ class Posting(Base): account_id: Mapped[uuid.UUID] = mapped_column( UUID(as_uuid=True), ForeignKey("account.id"), nullable=False ) - # Denormalized from account.customer_id, trigger-set (posting_before_insert below). Never - # written by application code -- see module docstring. + # Denormalized from account.customer_id, trigger-set (posting_before_insert below). customer_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), nullable=True) amount_money: Mapped[Money | None] = mapped_column(MoneyType, nullable=True) quantity_units: Mapped[Units | None] = mapped_column(UnitsType, nullable=True) @@ -143,8 +130,7 @@ class Posting(Base): ), ) -# --- RLS: role-aware tenant isolation, `posting`'s own policy since its tenant key is -# denormalized rather than native (S1 §3.3, S0 §7.3, ADR 17) --------------------------------- +# RLS: role-aware tenant isolation, own policy since the tenant key is denormalized (S0 §7.3, ADR 17). event.listen( Posting.__table__, diff --git a/backend/app/models/ledger/settlement_obligation.py b/backend/app/models/ledger/settlement_obligation.py index 0c12742..f844f1f 100644 --- a/backend/app/models/ledger/settlement_obligation.py +++ b/backend/app/models/ledger/settlement_obligation.py @@ -1,11 +1,7 @@ -"""`settlement_obligation` (S1 §4, ADR 2) — tracks whether the custodian has confirmed a cash -movement the ledger already posted economically. Never posts to the ledger on a state transition. - -`status` transitions exactly once, `pending` -> `confirmed` | `failed` (§6): a `BEFORE UPDATE` -trigger rejects any update once the current row is already terminal, so this table mutates in -exactly one controlled way -- unlike `journal_entry`/`posting`, which never mutate at all. `DELETE` -is still revoked at the database (part of this migration's grants) since an obligation is a -regulatory-relevant record of what was expected to settle and when. +"""`settlement_obligation` (S1 §4, ADR 2) — tracks whether the custodian confirmed a cash movement +the ledger already posted. Never posts to the ledger on a state transition. + +`status` transitions exactly once, `pending -> confirmed | failed`, via a `BEFORE UPDATE` trigger; `DELETE` is revoked. """ from __future__ import annotations @@ -103,8 +99,7 @@ class SettlementObligation(Base): ), ) -# DELETE is revoked, matching journal_entry/posting's append-only posture (module docstring); -# UPDATE stays granted for the one-time status transition the trigger above polices. +# DELETE revoked; UPDATE stays granted for the one-time status transition above. event.listen( SettlementObligation.__table__, "after_create", @@ -113,9 +108,7 @@ class SettlementObligation(Base): class SettlementObligationRepository(BaseRepository[SettlementObligation]): - """No `customer_id_column`: like `journal_entry`, `settlement_obligation` carries no - customer identity of its own in S1 §4's schema -- per-customer reads compose with `posting`/ - `account` via `journal_entry_id`/`account_id`, matching `JournalEntryRepository`.""" + """No `customer_id_column`: per-customer reads compose with `posting`/`account`.""" def __init__(self, uow: UnitOfWork) -> None: super().__init__(uow, entity=SettlementObligation) diff --git a/backend/app/models/ledger/tax_lot.py b/backend/app/models/ledger/tax_lot.py index c891ff8..95a17c8 100644 --- a/backend/app/models/ledger/tax_lot.py +++ b/backend/app/models/ledger/tax_lot.py @@ -1,11 +1,7 @@ """`tax_lot` (S5 §3.1) — one row per buy fill, never merged even for same-day same-security fills. -Mutable, unlike `journal_entry`/`posting`: it is a *projection* derived from the immutable ledger -(the same shape of problem `order` solves for `order_event`, S3 §3.1) — `quantity_remaining` and -`adjusted_basis` both shrink/grow in place as sells consume the lot and wash-sale adjustments carry -disallowed loss into it (ADR 11). `quantity_remaining >= 0` is enforced by a genuine database -`CHECK` (S5 §3.1's edge case 6, §8's own integration-testing emphasis) since a negative value is a -direct sign of a lot-consumption bug, never a valid state. +Mutable projection: `quantity_remaining`/`adjusted_basis` shrink/grow in place as sells consume the +lot and wash-sale adjustments carry disallowed loss into it (ADR 11). `quantity_remaining >= 0` is a DB `CHECK`. """ from __future__ import annotations @@ -45,8 +41,7 @@ class LotDesignation(StrEnum): - """ADR 4: `unspecified` (FIFO applies) vs `specific` (investor override, closes no later than - `min(expected_settlement_date, confirmation_event)`).""" + """ADR 4: `unspecified` (FIFO) vs `specific` (investor override).""" UNSPECIFIED = "unspecified" SPECIFIC = "specific" @@ -67,8 +62,7 @@ class TaxLot(Base): security_id: Mapped[uuid.UUID] = mapped_column( UUID(as_uuid=True), ForeignKey("security.id"), nullable=False ) - # One lot per fill, never merged (module docstring) -- the FK target's own uniqueness - # (`uq_order_event_execution_id`) is what makes this column unique too. + # One lot per fill, never merged (module docstring). opening_fill_execution_id: Mapped[str] = mapped_column( String(255), ForeignKey("order_event.execution_id"), nullable=False, unique=True ) @@ -88,8 +82,7 @@ class TaxLot(Base): ) -# S0 §7.3's role-aware tenant-isolation RLS policy (ADR 17) -- `tax_lot` carries a native -# `customer_id`, same shape as `account`/`order`. +# Role-aware tenant-isolation RLS policy (S0 §7.3, ADR 17). event.listen( TaxLot.__table__, "after_create", @@ -113,10 +106,7 @@ class TaxLot(Base): ), ) -# F12/I3 fix (S0 §10.1 audit): a lot row is a mutable *projection* (module docstring) -- UPDATE is -# legitimate as `quantity_remaining`/`adjusted_basis`/`designation` change -- but it must never be -# deleted; the S5 migration that created this table carried no REVOKE at all, unlike every other -# money-bearing table in the schema. +# Mutable projection, but must never be deleted (S0 §10.1 F12/I3). event.listen( TaxLot.__table__, "after_create", @@ -132,11 +122,7 @@ def get_by_id(self, lot_id: uuid.UUID) -> TaxLot | None: return self.session.query(TaxLot).filter_by(id=lot_id).first() def lock_open_fifo(self, customer_id: uuid.UUID, security_id: uuid.UUID) -> list[TaxLot]: - """Open lots (`quantity_remaining > 0`) for one customer/security, oldest first (ADR 4's - FIFO default), row-locked for the duration of the consuming transaction -- the per-lot - analogue of `OrderRepository.get_for_update`, needed because two sell fills for the same - security could otherwise both read the same lot's `quantity_remaining` before either - writes it back.""" + """Open lots for one customer/security, oldest first, row-locked (ADR 4 FIFO default).""" statement = ( select(TaxLot) .where( @@ -150,9 +136,7 @@ def lock_open_fifo(self, customer_id: uuid.UUID, security_id: uuid.UUID) -> list return list(self.session.execute(statement).scalars().all()) def lock_by_ids(self, lot_ids: Sequence[uuid.UUID]) -> dict[uuid.UUID, TaxLot]: - """Specific-ID override path (ADR 4): row-locks exactly the designated lots. Returns a - dict rather than a list so the caller can re-apply the investor's own designation order - and detect a missing/foreign id.""" + """Specific-ID override path (ADR 4): row-locks exactly the designated lots.""" if not lot_ids: return {} statement = select(TaxLot).where(TaxLot.id.in_(lot_ids)).with_for_update() @@ -162,8 +146,7 @@ def lock_by_ids(self, lot_ids: Sequence[uuid.UUID]) -> dict[uuid.UUID, TaxLot]: def lock_open_for_security( self, customer_id: uuid.UUID, security_id: uuid.UUID ) -> list[TaxLot]: - """Every open lot for one customer/security, row-locked -- `CorporateActionService`'s - split path needs every lot touched atomically, not just a FIFO-ordered subset.""" + """Every open lot for one customer/security, row-locked (`CorporateActionService` split path).""" statement = ( select(TaxLot) .where( @@ -176,9 +159,7 @@ def lock_open_for_security( return list(self.session.execute(statement).scalars().all()) def list_customers_holding(self, security_id: uuid.UUID) -> list[uuid.UUID]: - """Distinct customers with an open position in `security_id` -- how - `CorporateActionService` finds who a dividend/split applies to, since lot state is the - only source of truth for holdings (no separate holdings table, S5 §1).""" + """Distinct customers with an open position in `security_id` (dividend/split fan-out).""" statement = ( select(TaxLot.customer_id) .where(TaxLot.security_id == security_id, TaxLot.quantity_remaining > Units("0")) @@ -187,9 +168,7 @@ def list_customers_holding(self, security_id: uuid.UUID) -> list[uuid.UUID]: return list(self.session.execute(statement).scalars().all()) def list_for_customer(self, customer_id: uuid.UUID) -> list[TaxLot]: - """Every lot ever opened for this customer, oldest-acquired first -- `GET /api/v1/lots` - (S8 §3) is a tax-detail screen, so a fully-consumed lot (`quantity_remaining == 0`) still - belongs in it, unlike `lock_open_fifo`'s trading-time filter.""" + """Every lot ever opened for this customer, oldest-acquired first (`GET /api/v1/lots`, S8 §3).""" statement = ( select(TaxLot) .where(TaxLot.customer_id == customer_id) @@ -198,8 +177,7 @@ def list_for_customer(self, customer_id: uuid.UUID) -> list[TaxLot]: return list(self.session.execute(statement).scalars().all()) def list_by_ids(self, lot_ids: Sequence[uuid.UUID]) -> list[TaxLot]: - """Plain, non-locking bulk fetch -- unlike `lock_by_ids`, for a read-only consumer (the - statement export, S8 §5) that has no consuming transaction to hold a row lock for.""" + """Plain, non-locking bulk fetch, for a read-only consumer (statement export, S8 §5).""" if not lot_ids: return [] statement = select(TaxLot).where(TaxLot.id.in_(lot_ids)) @@ -221,8 +199,7 @@ def find_earliest_replacement_in_window( window_end: date, exclude_lot_id: uuid.UUID, ) -> TaxLot | None: - """ADR 11's same-CUSIP repurchase match: the earliest buy within the trailing/forward - 30-day window, excluding the lot the loss sale itself drew down.""" + """ADR 11's same-CUSIP repurchase match: earliest buy in the window, excluding the sold lot.""" statement = ( select(TaxLot) .where( diff --git a/backend/app/models/ledger/wash_sale_adjustment.py b/backend/app/models/ledger/wash_sale_adjustment.py index d6cf6ec..a6381a8 100644 --- a/backend/app/models/ledger/wash_sale_adjustment.py +++ b/backend/app/models/ledger/wash_sale_adjustment.py @@ -1,12 +1,6 @@ -"""`wash_sale_adjustment` (S5 §3.3, ADR 11) — the record of a disallowed loss carried into a -replacement lot's basis. - -References `lot_consumption`/`tax_lot` by table name only (`ForeignKey("lot_consumption.id")`), -never by importing those modules -- `lot_consumption.py` imports *this* module (to query "has this -consumption already been adjusted"), so importing back would cycle. `UniqueConstraint` on -`original_lot_consumption_id`: ADR 11's mechanism disallows a given loss sale's loss exactly once --- a chained wash sale (S5 §7 edge case 2) is a *different* consumption row (the replacement lot's -own later sale), never a second adjustment against the same one. +"""`wash_sale_adjustment` (S5 §3.3, ADR 11) — record of a disallowed loss carried into a +replacement lot's basis. References `lot_consumption`/`tax_lot` by table name only to avoid an +import cycle. `UniqueConstraint` on `original_lot_consumption_id` disallows a loss exactly once. """ from __future__ import annotations @@ -45,10 +39,7 @@ class WashSaleAdjustment(Base): ) -# F12/I3 fix (S0 §10.1 audit): unlike `tax_lot`/`lot_consumption`, this row is never mutated once -# written -- it is itself the immutable correction record ADR 11's mechanism produces, its own -# uniqueness enforcing "exactly once." The S5 migration that created this table carried no REVOKE -# at all, unlike every other money-bearing table in the schema. +# Immutable correction record; never mutated once written (S0 §10.1 F12/I3). event.listen( WashSaleAdjustment.__table__, "after_create", @@ -59,8 +50,7 @@ class WashSaleAdjustment(Base): class WashSaleAdjustmentRepository(BaseRepository[WashSaleAdjustment]): - """No `customer_id_column`: no native customer identity (module docstring's schema), matching - `lot_consumption`'s precedent -- per-customer reads join through `tax_lot`.""" + """No `customer_id_column`: per-customer reads join through `tax_lot`.""" def __init__(self, uow: UnitOfWork) -> None: super().__init__(uow, entity=WashSaleAdjustment) diff --git a/backend/app/models/marketdata/__init__.py b/backend/app/models/marketdata/__init__.py index 927f2ed..475d74d 100644 --- a/backend/app/models/marketdata/__init__.py +++ b/backend/app/models/marketdata/__init__.py @@ -14,7 +14,7 @@ class MarketDataUnitOfWork(UnitOfWork): - """A `UnitOfWork` exposing the repositories S4 owns (S0 §5's documented extension mechanism).""" + """`UnitOfWork` exposing the repositories S4 owns (S0 §5).""" @cached_property def securities(self) -> SecurityRepository: diff --git a/backend/app/models/marketdata/daily_close.py b/backend/app/models/marketdata/daily_close.py index 96321bd..2049795 100644 --- a/backend/app/models/marketdata/daily_close.py +++ b/backend/app/models/marketdata/daily_close.py @@ -1,15 +1,7 @@ """`daily_close` (S4 §3.1) — one row per confirmed/stale close a provider ever reported. -Bitemporal, append-only, matching `journal_entry`/`posting`'s posture (ADR 1 extended to price -data): a corrected close for the same `market_date` is a **new row**, never an `UPDATE` -- S6's -restatement mechanism depends on being able to see what the close was *as of* any prior watermark. - -**`missing` is never a stored row (S4 §6).** No close arriving at all by the valuation cutoff is -represented by the *absence* of a `confirmed` row for that `(security_id, market_date)` -- -`ValuationService` infers `missing` from that absence, exactly as the spec requires ("inferred by -absence, not stored as a row"). The `MISSING` enum member exists for schema completeness (a -provider could in principle report an explicit missing/withdrawn signal) but no code path in this -sub-project writes one. +Bitemporal, append-only (ADR 1 extended to price data): a corrected close is a new row, never an +`UPDATE`. `missing` is inferred by absence of a `confirmed` row, never stored (S4 §6). """ from __future__ import annotations @@ -38,8 +30,7 @@ class MarketDataSource(StrEnum): - """NFR-12's "market data live or simulated, clearly labelled" rule -- shared by `daily_close` - and `market_calendar_cache` (S4 §3.1/§3.4).""" + """NFR-12: market data live or simulated, clearly labelled (S4 §3.1/§3.4).""" LIVE = "live" SIMULATED = "simulated" @@ -49,7 +40,7 @@ class DailyCloseStatus(StrEnum): CONFIRMED = "confirmed" STALE = "stale" MISSING = "missing" - """Never written by this sub-project's own code paths -- see module docstring.""" + """Never written by this sub-project's code paths (see module docstring).""" class DailyClose(Base): @@ -83,8 +74,7 @@ class DailyClose(Base): class DailyCloseRepository(BaseRepository[DailyClose]): - """No `customer_id_column`: prices are not tenant-scoped. Append-only (S4 §3.1) -- a - correction is always a new row with a later `recorded_at`, never an `UPDATE`.""" + """No `customer_id_column`: prices are not tenant-scoped. Append-only (S4 §3.1).""" append_only = True @@ -92,8 +82,7 @@ def __init__(self, uow: UnitOfWork) -> None: super().__init__(uow, entity=DailyClose, recorded_at_column=DailyClose.recorded_at) def latest_confirmed(self, *, security_id: uuid.UUID, market_date: date) -> DailyClose | None: - """The latest-`recorded_at` `confirmed` close for this security/date (S4 §4's - `value_book` read, S4 §8 case 5: always the newest correction, however many followed).""" + """The latest-`recorded_at` `confirmed` close for this security/date (S4 §4).""" return ( self.session.query(DailyClose) .filter_by( @@ -106,8 +95,7 @@ def latest_confirmed(self, *, security_id: uuid.UUID, market_date: date) -> Dail ) def latest(self, *, security_id: uuid.UUID, market_date: date) -> DailyClose | None: - """The latest-`recorded_at` row regardless of status -- used to classify `stale` vs. - genuinely absent (S4 §6).""" + """The latest-`recorded_at` row regardless of status; classifies `stale` vs. absent (S4 §6).""" return ( self.session.query(DailyClose) .filter_by(security_id=security_id, market_date=market_date) diff --git a/backend/app/models/marketdata/market_calendar_cache.py b/backend/app/models/marketdata/market_calendar_cache.py index 2d759e1..29c2520 100644 --- a/backend/app/models/marketdata/market_calendar_cache.py +++ b/backend/app/models/marketdata/market_calendar_cache.py @@ -1,12 +1,6 @@ -"""`market_calendar_cache` (S4 §3.4, ADR 12) — `MarketClock` reads it via a `TradingCalendar` -adapter (`trading_calendar.py` in this package); `CalendarPort → Alpaca` populates it. +"""`market_calendar_cache` (S4 §3.4, ADR 12) — read via `TradingCalendar`/`trading_calendar.py`. -**A cache miss is never a holiday (S4 §3.4).** This table is a cache keyed on `market_date`, not a -bitemporal correction ledger like `daily_close` — a row is upserted in place as the source of truth -for that date, since "was 2026-01-01 a trading day" has exactly one right answer, not a history of -corrected answers. An absent row means the calendar has not been fetched for that date yet, which -`MarketCalendarCacheRepository.get()` returning `None` must let the caller distinguish from -`is_trading_day = False` — collapsing the two is exactly the bug this table exists to prevent. +Upserted in place, keyed on `market_date`. A cache miss (`get()` returns `None`) is never a holiday. """ from __future__ import annotations @@ -47,16 +41,13 @@ class MarketCalendarCache(Base): class MarketCalendarCacheRepository(BaseRepository[MarketCalendarCache]): - """No `customer_id_column`: the calendar is not tenant-scoped. Not append-only: this is a - cache upserted in place (module docstring), unlike `daily_close`'s bitemporal correction - trail.""" + """No `customer_id_column`: not tenant-scoped. Not append-only: a cache upserted in place.""" def __init__(self, uow: UnitOfWork) -> None: super().__init__(uow, entity=MarketCalendarCache) def get(self, market_date: date_) -> MarketCalendarCache | None: - """`None` means "not yet fetched" -- never conflate with a fetched `is_trading_day=False` - row (module docstring).""" + """`None` means "not yet fetched"; never conflate with a fetched `is_trading_day=False` row.""" return ( self.session.query(MarketCalendarCache) .filter_by(market_date=market_date) @@ -64,8 +55,7 @@ def get(self, market_date: date_) -> MarketCalendarCache | None: ) def upsert(self, row: MarketCalendarCache) -> MarketCalendarCache: - """Insert, or replace in place if this date was already cached (e.g. a provider - correction to a previously-fetched half-day).""" + """Insert, or replace in place if this date was already cached.""" existing = self.get(row.market_date) if existing is None: self.add(row) diff --git a/backend/app/models/marketdata/security.py b/backend/app/models/marketdata/security.py index c21772b..1ec89a8 100644 --- a/backend/app/models/marketdata/security.py +++ b/backend/app/models/marketdata/security.py @@ -1,13 +1,7 @@ """`security` (S4 §3.3) — the instrument master. -Deliberately minimal: exchange, CUSIP, fractional-share eligibility, and corporate-action metadata -are out of scope here (deferred / owned by S5). A security is added by an operator or seeded from a -model portfolio's target weights (S9) — there is no customer-facing endpoint that creates one, so -`symbol` is never user-supplied input. - -No FK from `account.security_id` / `order.security_id` to this table: both were written before -this spec existed (S1 §3.1's own comment says so) and are out of this task's files to touch, -per S4 §3.3. +Deliberately minimal; no customer-facing endpoint creates one, so `symbol` is never user input. +No FK from `account.security_id`/`order.security_id`; both predate this spec (S4 §3.3). """ from __future__ import annotations @@ -66,9 +60,7 @@ class Security(Base): class SecurityRepository(BaseRepository[Security]): - """No `customer_id_column`: a security is not tenant-scoped -- every customer can reference - the same instrument master row (matching `InboundEventRepository`'s precedent for a table with - no customer identity).""" + """No `customer_id_column`: a security is not tenant-scoped.""" def __init__(self, uow: UnitOfWork) -> None: super().__init__(uow, entity=Security) diff --git a/backend/app/models/marketdata/sub_period_return.py b/backend/app/models/marketdata/sub_period_return.py index dff4373..82af8a0 100644 --- a/backend/app/models/marketdata/sub_period_return.py +++ b/backend/app/models/marketdata/sub_period_return.py @@ -1,10 +1,7 @@ """`sub_period_return` (S4 §3.5, ADR 3) — one stored row per TWR sub-period. -ADR 3's claimed restatement property ("a correction touches exactly one sub-period") is only -literally true if each sub-period's return is *stored*, not recomputed end-to-end on every read. -Bitemporal and append-only, matching `daily_close`'s posture: a restated sub-period is a **new -row**, never an `UPDATE`. `TwrService` reads the latest `recorded_at` per `(customer_id, -sub_period_start, sub_period_end)`; S6 pins to the watermark live at publication. +Bitemporal and append-only: a restated sub-period is a new row, never an `UPDATE`. `TwrService` +reads the latest `recorded_at` per `(customer_id, sub_period_start, sub_period_end)`. """ from __future__ import annotations @@ -49,9 +46,7 @@ class SubPeriodReturn(Base): ) sub_period_start: Mapped[date] = mapped_column(SQLAlchemyDate, nullable=False) sub_period_end: Mapped[date] = mapped_column(SQLAlchemyDate, nullable=False) - # Wider than Money's 4dp (S4 §3.5): a linked product compounds rounding error, and this is a - # ratio, not a money/units/price dimension, so it deliberately stays a plain Decimal rather - # than one of ADR 16's value objects. + # Wider than Money's 4dp (S4 §3.5); a ratio, not a money/units/price dimension (ADR 16). return_pct: Mapped[Decimal] = mapped_column(Numeric(18, 10), nullable=False) value_begin: Mapped[Money] = mapped_column(MoneyType, nullable=False) value_end: Mapped[Money] = mapped_column(MoneyType, nullable=False) @@ -76,8 +71,7 @@ def __init__(self, uow: UnitOfWork) -> None: def latest_for_sub_period( self, *, customer_id: uuid.UUID, sub_period_start: date, sub_period_end: date ) -> SubPeriodReturn | None: - """The newest-`recorded_at` stored row for this exact sub-period, if one exists yet - (`TwrService`'s reuse-or-recompute decision, S4 §5).""" + """The newest-`recorded_at` stored row for this sub-period, if one exists (S4 §5).""" return ( self.session.query(SubPeriodReturn) .filter_by( @@ -97,9 +91,7 @@ def as_of_for_sub_period( sub_period_end: date, as_of: Watermark, ) -> SubPeriodReturn | None: - """The newest-`recorded_at` row for this exact sub-period visible as of a past watermark - (S6 §6/§7) -- the module docstring's "S6 pins to the watermark live at publication", - made concrete for `SnapshotService.derive()`.""" + """The newest-`recorded_at` row for this sub-period visible as of a past watermark (S6 §6/§7).""" return ( self.session.query(SubPeriodReturn) .filter( @@ -113,12 +105,7 @@ def as_of_for_sub_period( ) def containing(self, *, customer_id: uuid.UUID, on_date: date) -> list[SubPeriodReturn]: - """The latest-`recorded_at` row for every *distinct* stored `[sub_period_start, - sub_period_end]` window containing `on_date` (S6 §5: "recompute exactly the - `sub_period_return` row(s) whose window contains `affected_date`"). Usually exactly one - row -- more than one only when a customer has more than one reporting period (e.g. a - calendar-month and a calendar-quarter statement) whose sub-periods both happen to span - the same date.""" + """The latest-`recorded_at` row for every distinct stored window containing `on_date` (S6 §5).""" statement = ( select(SubPeriodReturn) .where( diff --git a/backend/app/models/marketdata/trading_calendar.py b/backend/app/models/marketdata/trading_calendar.py index 6e2322d..128f452 100644 --- a/backend/app/models/marketdata/trading_calendar.py +++ b/backend/app/models/marketdata/trading_calendar.py @@ -1,18 +1,6 @@ -"""`CachedTradingCalendar` — the `TradingCalendar` (`app/core/clock.py`) implementation that reads -`market_calendar_cache` (S4 §3.4), so `MarketClock` can convert UTC instants to market days without -`app/core/` ever importing a model (ADR 12, S0 §3's layering constraint). - -Placed in the model layer, not services: this class has no business logic beyond the query itself -and the honest-degradation rule below -- the same weight class as `BaseRepository` itself, one layer -below where `ValuationService`/`TwrService` live. - -**A cache miss raises, it never silently reads as a holiday.** `TradingCalendar.is_trading_day()` -and `session_close()` are declared to return a plain `bool`/`datetime | None` with no error channel, -but S4 §3.4 is explicit that an absent cache row is an operational condition ("the calendar has -not been fetched for that date"), not evidence of a holiday -- collapsing the two would silently -suppress exactly the missed-valuation alert §6 and S0 §10.7 exist to raise. -`MarketCalendarCacheMissError` is that operational condition surfacing as loudly as the Protocol's -shape allows: raised rather than returned, so a caller cannot accidentally treat it as `False`. +"""`CachedTradingCalendar` — `TradingCalendar` (`app/core/clock.py`) implementation reading +`market_calendar_cache` (S4 §3.4, ADR 12). A cache miss raises `MarketCalendarCacheMissError`, +never silently reads as a holiday. """ from __future__ import annotations @@ -26,15 +14,11 @@ class MarketCalendarCacheMissError(RuntimeError): - """`market_calendar_cache` has no row for this date yet (S4 §3.4) — the calendar has not been - fetched, which is distinct from (and must never be conflated with) a fetched holiday.""" + """`market_calendar_cache` has no row for this date yet; distinct from a fetched holiday (S4 §3.4).""" class CachedTradingCalendar: - """Satisfies `app.core.clock.TradingCalendar` by querying `market_calendar_cache` through the - injected repository. `CalendarPort → Alpaca` is what populates the cache this class only reads - (`ports.py`'s `CalendarPort` docstring: the two are connected by the cache, not by calling each - other directly).""" + """Satisfies `app.core.clock.TradingCalendar` by querying `market_calendar_cache`.""" def __init__(self, repository: MarketCalendarCacheRepository) -> None: self._repository = repository diff --git a/backend/app/models/marketdata/valuation_run.py b/backend/app/models/marketdata/valuation_run.py index 8389c01..f95cefb 100644 --- a/backend/app/models/marketdata/valuation_run.py +++ b/backend/app/models/marketdata/valuation_run.py @@ -1,13 +1,6 @@ """`valuation_run` (S4 §3.2) — one row per `market_date` `DailyValuationJob` processes. -Not in the team-lead brief's explicit file list for this wave, but named and schema'd in full by S4 -§3.2 and required by §4/§6/§8 case 4 (`ValuationService`/`TwrService` both need to know whether a -day's valuation was `complete` or `partial`) and by the foundation spec's own S4 surface map -(`DailyValuationJob`). Built here rather than skipped -- omitting it would leave "the whole-book -`partial` condition" (S4 §6) unimplementable, which is a spec requirement, not an enhancement. - -Upserted in place per `market_date`, like `market_calendar_cache` -- "did today's valuation run -complete" has one right answer per day, not a bitemporal correction history. +Upserted in place per `market_date`, like `market_calendar_cache`; not a bitemporal correction history. """ from __future__ import annotations diff --git a/backend/app/models/ops/__init__.py b/backend/app/models/ops/__init__.py index 595a426..ae492da 100644 --- a/backend/app/models/ops/__init__.py +++ b/backend/app/models/ops/__init__.py @@ -7,6 +7,7 @@ from sqlalchemy import text from app.core.uow import UnitOfWork +from app.models.ops.agent_action_request import AgentActionRequestRepository from app.models.ops.inbound_event import InboundEventRepository from app.models.ops.job_outbox import JobOutboxRepository from app.models.ops.job_run import JobRunRepository @@ -27,6 +28,10 @@ def outbox(self) -> JobOutboxRepository: def job_runs(self) -> JobRunRepository: return JobRunRepository(self) + @cached_property + def agent_action_requests(self) -> AgentActionRequestRepository: + return AgentActionRequestRepository(self) + def notify_outbox_ready(self) -> None: """Queue a Postgres notification in this transaction with the outbox insert.""" self.session.execute(text("SELECT pg_notify('job_outbox_ready', 'ready')")) diff --git a/backend/app/models/ops/admin_audit_log.py b/backend/app/models/ops/admin_audit_log.py index a19a024..df3a681 100644 --- a/backend/app/models/ops/admin_audit_log.py +++ b/backend/app/models/ops/admin_audit_log.py @@ -28,9 +28,7 @@ class AdminAuditLog(Base): id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) actor_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), nullable=False) action: Mapped[str] = mapped_column(String(255), nullable=False) - # Nullable: an audited action need not always have a single-customer target (e.g. resolving a - # reconciliation_break with no customer attribution, S7 §5.2) -- the actor/action/payload-hash - # audit trail still applies; there is simply no customer to index it under for that one row. + # Nullable: an audited action need not always have a single-customer target (S7 §5.2). target_customer_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), nullable=True) payload_hash: Mapped[str] = mapped_column(String(64), nullable=False) recorded_at: Mapped[datetime] = mapped_column( diff --git a/backend/app/models/ops/agent_action_request.py b/backend/app/models/ops/agent_action_request.py new file mode 100644 index 0000000..d2e2f65 --- /dev/null +++ b/backend/app/models/ops/agent_action_request.py @@ -0,0 +1,279 @@ +"""`agent_action_request` (S13 §3.1, ADR 24) — one row per MCP write-tool proposal. + +Two-hop transition graph: `pending -> {approved, rejected}`, then `approved -> {executed, +execution_failed}`, enforced by a `BEFORE UPDATE` trigger (extends `reconciliation_break`'s +pattern). +""" + +from __future__ import annotations + +import uuid +from datetime import ( + datetime, # noqa: TC003 -- SQLAlchemy resolves mapped annotations at import time. +) +from enum import StrEnum +from typing import TYPE_CHECKING, Any + +from sqlalchemy import DDL, CheckConstraint, DateTime, Index, String, event, func, select, tuple_ +from sqlalchemy import Enum as SQLAlchemyEnum +from sqlalchemy.dialects.postgresql import JSONB, UUID +from sqlalchemy.orm import Mapped, mapped_column + +from app.core.repository import BaseRepository +from app.models.base import Base + +if TYPE_CHECKING: + from app.core.uow import UnitOfWork + + +def _enum_values(enum_class: type[StrEnum]) -> list[str]: + return [member.value for member in enum_class] + + +class AgentActionType(StrEnum): + RESOLVE_BREAK = "resolve_break" + KYC_OVERRIDE = "kyc_override" + REBALANCE = "rebalance" + + +class AgentActionStatus(StrEnum): + PENDING = "pending" + APPROVED = "approved" + REJECTED = "rejected" + EXECUTED = "executed" + EXECUTION_FAILED = "execution_failed" + + +class AgentActionRequest(Base): + __tablename__ = "agent_action_request" + __table_args__ = ( + CheckConstraint( + "(status NOT IN ('approved','rejected')) " + "OR (reviewed_by IS NOT NULL AND reviewed_at IS NOT NULL)", + name="review_requires_reviewer", + ), + CheckConstraint( + "(status <> 'executed') OR (executed_at IS NOT NULL)", + name="executed_requires_timestamp", + ), + CheckConstraint( + "(status <> 'execution_failed') OR (execution_error IS NOT NULL)", + name="failure_requires_error", + ), + CheckConstraint( + "length(justification) > 0", name="justification_present" + ), + Index("ix_agent_action_request_status_created", "status", "created_at"), + ) + + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + action: Mapped[AgentActionType] = mapped_column( + SQLAlchemyEnum(AgentActionType, name="agent_action_type", values_callable=_enum_values), + nullable=False, + ) + arguments: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False) + requesting_agent: Mapped[str] = mapped_column(String, nullable=False) + justification: Mapped[str] = mapped_column(String, nullable=False) + status: Mapped[AgentActionStatus] = mapped_column( + SQLAlchemyEnum(AgentActionStatus, name="agent_action_status", values_callable=_enum_values), + nullable=False, + default=AgentActionStatus.PENDING, + server_default=AgentActionStatus.PENDING.value, + ) + # No FK: predates a formal cross-schema FK convention (matches + # reconciliation_break.resolved_by). + reviewed_by: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), nullable=True) + reviewed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True) + review_note: Mapped[str | None] = mapped_column(String, nullable=True) + execution_error: Mapped[str | None] = mapped_column(String, nullable=True) + executed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True) + created_at: Mapped[datetime] = mapped_column( + DateTime(timezone=True), nullable=False, server_default=func.now() + ) + + +_SINGLE_TRANSITION_FUNCTION = DDL( # type: ignore[no-untyped-call] + """ + CREATE OR REPLACE FUNCTION agent_action_request_single_transition() RETURNS trigger AS $$ + BEGIN + IF OLD.status = 'pending' THEN + IF NEW.status NOT IN ('approved', 'rejected') THEN + RAISE EXCEPTION + 'agent_action_request %% may only move from pending to approved or rejected (got %%)', + OLD.id, NEW.status; + END IF; + ELSIF OLD.status = 'approved' THEN + IF NEW.status NOT IN ('executed', 'execution_failed') THEN + RAISE EXCEPTION + 'agent_action_request %% may only move approved -> executed/execution_failed (got %%)', + OLD.id, NEW.status; + END IF; + ELSE + RAISE EXCEPTION 'agent_action_request %% is already terminal (%%) and cannot be updated', + OLD.id, OLD.status; + END IF; + IF NEW.action <> OLD.action + OR NEW.arguments IS DISTINCT FROM OLD.arguments + OR NEW.requesting_agent <> OLD.requesting_agent + OR NEW.justification <> OLD.justification + OR NEW.created_at <> OLD.created_at THEN + RAISE EXCEPTION + 'agent_action_request %% identifying fields are immutable once created (S13 section 3.1)', + OLD.id; + END IF; + RETURN NEW; + END; + $$ LANGUAGE plpgsql; + """ +) + +_SINGLE_TRANSITION_TRIGGER = DDL( # type: ignore[no-untyped-call] + """ + CREATE TRIGGER agent_action_request_before_update + BEFORE UPDATE ON agent_action_request + FOR EACH ROW EXECUTE FUNCTION agent_action_request_single_transition(); + """ +) + +for _ddl in (_SINGLE_TRANSITION_FUNCTION, _SINGLE_TRANSITION_TRIGGER): + event.listen(AgentActionRequest.__table__, "after_create", _ddl) + +event.listen( + AgentActionRequest.__table__, + "before_drop", + DDL( # type: ignore[no-untyped-call] + "DROP TRIGGER IF EXISTS agent_action_request_before_update ON agent_action_request;" + "DROP FUNCTION IF EXISTS agent_action_request_single_transition();" + ), +) + +# Append-only in spirit (ADR 24): DELETE revoked; the trigger above polices legal UPDATEs. +event.listen( + AgentActionRequest.__table__, + "after_create", + DDL( # type: ignore[no-untyped-call] + "REVOKE DELETE ON agent_action_request FROM trueup_app, trueup_worker;" + ), +) + +# No RLS policy (S13 §3.1): access control is @requires_role("adviser", "admin") on every route. + + +class InvalidAgentActionTransitionError(RuntimeError): + """Raised when the application layer catches an illegal status transition before the DB + trigger would.""" + + +class AgentActionRequestRepository(BaseRepository[AgentActionRequest]): + """No `customer_id_column`: adviser/admin-scoped, not customer-scoped (S13 §3.1).""" + + def __init__(self, uow: UnitOfWork) -> None: + super().__init__(uow, entity=AgentActionRequest) + + def create( + self, + *, + action: AgentActionType, + arguments: dict[str, Any], + requesting_agent: str, + justification: str, + ) -> uuid.UUID: + """The only way an `agent_action_request` row is born (ADR 24). Flushes to return the + new id.""" + row = AgentActionRequest( + action=action, + arguments=arguments, + requesting_agent=requesting_agent, + justification=justification, + ) + self.session.add(row) + self.session.flush() + return row.id + + def get_by_id(self, request_id: uuid.UUID) -> AgentActionRequest | None: + return self.session.query(AgentActionRequest).filter_by(id=request_id).first() + + def get_for_update(self, request_id: uuid.UUID) -> AgentActionRequest | None: + """`SELECT ... FOR UPDATE`: two advisers approving/rejecting concurrently must + serialize (S13 §6).""" + statement = ( + select(AgentActionRequest).where(AgentActionRequest.id == request_id).with_for_update() + ) + return self.session.execute(statement).scalar_one_or_none() + + def list_by_status( + self, + status: AgentActionStatus, + *, + limit: int, + after: tuple[datetime, uuid.UUID] | None = None, + ) -> list[AgentActionRequest]: + """Keyset-paginated on `(created_at, id)`, oldest first (fetches `limit + 1`).""" + statement = select(AgentActionRequest).where(AgentActionRequest.status == status) + if after is not None: + after_created_at, after_id = after + key = tuple_(AgentActionRequest.created_at, AgentActionRequest.id) + statement = statement.where(key > (after_created_at, after_id)) + statement = statement.order_by( + AgentActionRequest.created_at.asc(), AgentActionRequest.id.asc() + ).limit(limit + 1) + return list(self.session.execute(statement).scalars().all()) + + def approve( + self, + row: AgentActionRequest, + *, + reviewed_by: uuid.UUID, + reviewed_at: datetime, + review_note: str | None, + ) -> None: + if row.status is not AgentActionStatus.PENDING: + raise InvalidAgentActionTransitionError( + f"agent_action_request {row.id} is {row.status}, not pending; cannot approve" + ) + row.status = AgentActionStatus.APPROVED + row.reviewed_by = reviewed_by + row.reviewed_at = reviewed_at + row.review_note = review_note + + def reject( + self, + row: AgentActionRequest, + *, + reviewed_by: uuid.UUID, + reviewed_at: datetime, + review_note: str, + ) -> None: + if row.status is not AgentActionStatus.PENDING: + raise InvalidAgentActionTransitionError( + f"agent_action_request {row.id} is {row.status}, not pending; cannot reject" + ) + row.status = AgentActionStatus.REJECTED + row.reviewed_by = reviewed_by + row.reviewed_at = reviewed_at + row.review_note = review_note + + def mark_executed(self, row: AgentActionRequest, *, executed_at: datetime) -> None: + if row.status is not AgentActionStatus.APPROVED: + raise InvalidAgentActionTransitionError( + f"agent_action_request {row.id} is {row.status}, not approved; cannot execute" + ) + row.status = AgentActionStatus.EXECUTED + row.executed_at = executed_at + + def mark_execution_failed(self, row: AgentActionRequest, *, execution_error: str) -> None: + if row.status is not AgentActionStatus.APPROVED: + raise InvalidAgentActionTransitionError( + f"agent_action_request {row.id} is {row.status}, not approved; cannot fail" + ) + row.status = AgentActionStatus.EXECUTION_FAILED + row.execution_error = execution_error + + +__all__ = [ + "AgentActionRequest", + "AgentActionRequestRepository", + "AgentActionStatus", + "AgentActionType", + "InvalidAgentActionTransitionError", +] diff --git a/backend/app/models/ops/idempotency_key.py b/backend/app/models/ops/idempotency_key.py index 84e94d8..162f3eb 100644 --- a/backend/app/models/ops/idempotency_key.py +++ b/backend/app/models/ops/idempotency_key.py @@ -37,10 +37,7 @@ class IdempotencyKey(Base): ) -# I9 fix (S0 §10.1 audit): `idempotency_key` is tenant-scoped -- `response_body` caches a -# customer's own order/funding response, financial PII -- but was the only tenant-scoped table in -# the schema with no RLS policy at all, every one of its 23 siblings has one. Matches the -# standard `tenant_isolation` predicate exactly (S0 §7.3, ADR 17). +# RLS policy, tenant_isolation predicate (S0 §7.3, ADR 17, S0 §10.1 I9). event.listen( IdempotencyKey.__table__, "after_create", diff --git a/backend/app/models/ops/inbound_event.py b/backend/app/models/ops/inbound_event.py index b85455e..bdcb4c3 100644 --- a/backend/app/models/ops/inbound_event.py +++ b/backend/app/models/ops/inbound_event.py @@ -82,8 +82,7 @@ def __init__(self, uow: UnitOfWork) -> None: def record(self, event: InboundEvent) -> None: try: - # A savepoint confines a duplicate-key failure so the caller can acknowledge the replay - # without discarding the surrounding transaction. + # Savepoint confines a duplicate-key failure without discarding the surrounding transaction. with self.session.begin_nested(): self.add(event) self.session.flush() @@ -93,7 +92,5 @@ def record(self, event: InboundEvent) -> None: raise def get_by_id(self, event_id: uuid.UUID) -> InboundEvent | None: - """The outbox payload for `process_inbound_event` carries only the id (`event_intake.py`) - -- this is how the dispatcher (`services/intake/dispatch.py`) resolves the row to read - `.source`/`.payload` from.""" + """How the dispatcher resolves the row to read `.source`/`.payload` from.""" return self.session.query(InboundEvent).filter_by(id=event_id).first() diff --git a/backend/app/models/ops/job_run.py b/backend/app/models/ops/job_run.py index 4eab793..091817b 100644 --- a/backend/app/models/ops/job_run.py +++ b/backend/app/models/ops/job_run.py @@ -73,15 +73,8 @@ class JobRun(Base): error: Mapped[str | None] = mapped_column(Text, nullable=True) -# Postgres's built-in date_trunc() is STABLE, not IMMUTABLE, so it cannot appear directly in the -# monthly partial-unique-index expression above ("functions in index expression must be marked -# IMMUTABLE"). market_date is a plain DATE (no timezone dependency), so truncating it to a month -# boundary is a pure function of its input in fact, just not declared that way by Postgres's own -# catalog. This wrapper function is the standard fix, and must exist before the index above is -# created — the Alembic migration creates it too (for `alembic upgrade head`), and this event -# mirrors that for any path that builds the schema via `Base.metadata.create_all()` instead (e.g. a -# test fixture creating a table subset directly, without running migrations). SQLAlchemy's -# DDL.__init__ ships with no type annotations, hence the ignore below. +# Postgres's date_trunc() is STABLE not IMMUTABLE, so it can't appear directly in the partial +# unique index above; this wrapper function is the standard fix. event.listen( JobRun.__table__, "before_create", diff --git a/backend/app/models/orders/__init__.py b/backend/app/models/orders/__init__.py index 6b1a42a..0a92f45 100644 --- a/backend/app/models/orders/__init__.py +++ b/backend/app/models/orders/__init__.py @@ -1,10 +1,7 @@ """Orders & custody model aggregates (S3): `order`, `order_event`, `approval_hold`. -The composed `UnitOfWork` combining these repositories with identity/ledger/ops (`OrdersUnitOfWork`) -lives in `app/services/orders/uow.py`, not here -- it depends on `IdentityUnitOfWork` -(`app/services/identity/uow.py`, services layer), and `app/models/` may not import `app/services/` -(S0 §3, enforced by `lint-imports`). `FundingUnitOfWork` (S2) is the identical precedent: also a -composed `UnitOfWork` living in `app/services/` for the same reason. +The composed `OrdersUnitOfWork` lives in `app/services/orders/uow.py`, not here, since `app/models/` +may not import `app/services/` (S0 §3). """ from __future__ import annotations diff --git a/backend/app/models/orders/_enum.py b/backend/app/models/orders/_enum.py index f766287..cda39ea 100644 --- a/backend/app/models/orders/_enum.py +++ b/backend/app/models/orders/_enum.py @@ -1,7 +1,6 @@ -"""Shared helper for mapping a `StrEnum` to its Postgres native enum, storing `.value` rather -than SQLAlchemy's default of `.name` — matching `app.models.ledger._enum.enum_values`. -Duplicated locally rather than imported cross-domain, same reasoning as that module's docstring: -`app/models/orders/` has no dependency on `app/models/ledger/`. +"""Maps a `StrEnum` to its Postgres native enum, storing `.value` not `.name`. + +Duplicated locally so `app/models/orders/` has no dependency on `app/models/ledger/`. """ from __future__ import annotations diff --git a/backend/app/models/orders/approval_hold.py b/backend/app/models/orders/approval_hold.py index 198652e..34341d7 100644 --- a/backend/app/models/orders/approval_hold.py +++ b/backend/app/models/orders/approval_hold.py @@ -1,12 +1,6 @@ -"""`approval_hold` (S3 §3.3) — the cash hold behind `awaiting_approval`/`approved`-but-not-yet- -`submitted` orders (S3 §4). Exactly one row per order (`order_id` is unique). - -`release_reason`'s enum covers every terminal-non-filled path (FR-38: `rejected`/`canceled`/ -`expired`) plus the happy-path exit, `approved_and_submitted` -- S3 §4's last paragraph scopes the -hold's active window to exactly `{awaiting_approval, approved-not-yet-submitted}`, so reaching -`submitted` ends that window exactly as much as a rejection does; the cash is then covered by -`open_buy_commitments` instead (`app.services.ledger.cash_policy_service`'s `HoldsProvider` -contract, owned by this sub-project). +"""`approval_hold` (S3 §3.3) — the cash hold behind `awaiting_approval`/not-yet-`submitted` orders +(S3 §4). Exactly one row per order. `release_reason` covers every terminal-non-filled path plus +`approved_and_submitted`; past that, cash is covered by `open_buy_commitments` instead. """ from __future__ import annotations @@ -73,8 +67,7 @@ class ApprovalHold(Base): ) -# S0 §7.3's role-aware tenant-isolation RLS policy (ADR 17) — `approval_hold` carries a native -# `customer_id`, same shape as `account`/`order`. +# Role-aware tenant-isolation RLS policy (S0 §7.3, ADR 17). event.listen( ApprovalHold.__table__, "after_create", @@ -98,10 +91,7 @@ class ApprovalHold(Base): ), ) -# F12/I3 fix (S0 §10.1 audit): `status`/`release_reason` legitimately update as a hold's lifecycle -# progresses, but `amount_money` is set once at open and a hold row must never be deleted -- it is -# the record of a cash commitment that either converted to `open_buy_commitments` or was released, -# never erased. The S3 migration that created this table carried no REVOKE at all. +# Row must never be deleted; it's the record of a cash commitment (S0 §10.1 F12/I3). event.listen( ApprovalHold.__table__, "after_create", @@ -119,8 +109,7 @@ def get_by_order_id(self, order_id: uuid.UUID) -> ApprovalHold | None: return self.session.query(ApprovalHold).filter_by(order_id=order_id).first() def active_total_for_customer(self, customer_id: uuid.UUID) -> Money: - """`CashPolicyService.HoldsProvider.holds` (S1 §5) -- the sum of every `active` hold for - this customer.""" + """`CashPolicyService.HoldsProvider.holds` (S1 §5): sum of every `active` hold.""" statement = self._tenant_scoped(select(ApprovalHold)).where( ApprovalHold.customer_id == customer_id, ApprovalHold.status == ApprovalHoldStatus.ACTIVE, diff --git a/backend/app/models/orders/order.py b/backend/app/models/orders/order.py index 8b82211..a8df828 100644 --- a/backend/app/models/orders/order.py +++ b/backend/app/models/orders/order.py @@ -1,12 +1,8 @@ """`order` (S3 §3.1) — the rebuildable projection (ADR 7). -`assert projection == fold(order_event)` is the standing invariant for everything `order_event`'s -`event_type` enum actually covers (`submitted` onward — `OrderProjectionService`). The -pre-submission portion of the lifecycle (`draft` -> `awaiting_approval` -> `approved`) has no -corresponding `event_type` (S3 §3.2's enum starts at `submitted`) because nothing external drives -it — it is written directly by `OrderService` as the customer/S9 caller and the approval endpoint -act, exactly as `journal_entry`/`posting` are the append-only truth while `account` is a plain -mutable row (S1 precedent, reused here for the same shape of problem). +`assert projection == fold(order_event)` holds from `submitted` onward. The pre-submission +lifecycle (`draft -> awaiting_approval -> approved`) has no `event_type`; `OrderService` writes it +directly (S1's `account`-vs-ledger precedent). """ from __future__ import annotations @@ -38,9 +34,7 @@ class OrderSide(StrEnum): class OrderStatus(StrEnum): - """S3 §4's state machine. `draft` is the transient pre-persistence value used only as the - `_write` starting point below; every row actually committed lands in `awaiting_approval` or - `approved` at the earliest (`OrderService.create_order` never leaves a row at `draft`).""" + """S3 §4's state machine. `draft` is transient; no committed row is ever left at `draft`.""" DRAFT = "draft" AWAITING_APPROVAL = "awaiting_approval" @@ -57,15 +51,11 @@ class OrderStatus(StrEnum): TERMINAL_NON_FILLED_STATUSES = frozenset( {OrderStatus.REJECTED, OrderStatus.CANCELED, OrderStatus.EXPIRED} ) -"""FR-38's "terminal non-filled state" set — the trigger for `ApprovalHoldService.release`.""" +"""FR-38's terminal non-filled state set; triggers `ApprovalHoldService.release`.""" def derive_client_order_id(order_id: uuid.UUID) -> str: - """S3 §3.1/§5: deterministic, derived from `order.id`, never regenerated on retry — a network - timeout on the broker `POST` can be safely retried with this same value (foundation §10 case - 2). A pure function so every caller (order creation, a retried outbox attempt) computes the - identical string with no state to keep in sync. - """ + """Deterministic, derived from `order.id`, never regenerated on retry (S3 §3.1/§5).""" return f"trueup-{order_id}" @@ -80,8 +70,7 @@ class Order(Base): customer_id: Mapped[uuid.UUID] = mapped_column( UUID(as_uuid=True), ForeignKey("customer.id"), nullable=False ) - # No FK: the securities catalogue is S5's to define (matches `account.security_id`'s - # precedent, S1 §3.1). + # No FK: the securities catalogue is S5's to define (matches account.security_id, S1 §3.1). security_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), nullable=False) side: Mapped[OrderSide] = mapped_column( SQLAlchemyEnum(OrderSide, name="order_side", values_callable=enum_values), nullable=False @@ -105,8 +94,7 @@ class Order(Base): ) -# S0 §7.3's role-aware tenant-isolation RLS policy (ADR 17) — `order` carries a native -# `customer_id`, same shape as `account`/`customer`. +# Role-aware tenant-isolation RLS policy (S0 §7.3, ADR 17). event.listen( Order.__table__, "after_create", @@ -139,11 +127,7 @@ def get_by_id(self, order_id: uuid.UUID) -> Order | None: return self.session.query(Order).filter_by(id=order_id).first() def get_for_update(self, order_id: uuid.UUID) -> Order | None: - """`SELECT ... FOR UPDATE`, serializing concurrent processors of this order's events — - the per-order analogue of `customer_cash_lock.acquire` (S1 §3.5), needed because two - `order_event`s for the same order can be claimed by two different outbox workers at once - (`JobOutboxRepository.claim_next`'s `SKIP LOCKED` only guarantees one *row* per worker, - not one *order* per worker).""" + """`SELECT ... FOR UPDATE`, serializing concurrent processors of this order's events.""" statement = self._tenant_scoped(select(Order)).where(Order.id == order_id).with_for_update() return self.session.execute(statement).scalar_one_or_none() @@ -159,8 +143,7 @@ def list_for_customer(self, customer_id: uuid.UUID) -> list[Order]: return list(self.session.execute(statement).scalars().all()) def open_buy_orders(self, customer_id: uuid.UUID) -> list[Order]: - """Buy orders past the approval-hold window but not yet resolved (S1 §5's - `open_buy_commitments` -- CashPolicyService's contract, owned here).""" + """Buy orders past the approval-hold window but not yet resolved (S1 §5 `open_buy_commitments`).""" statement = self._tenant_scoped(select(Order)).where( Order.customer_id == customer_id, Order.side == OrderSide.BUY, diff --git a/backend/app/models/orders/order_event.py b/backend/app/models/orders/order_event.py index e3888f3..dbbbc99 100644 --- a/backend/app/models/orders/order_event.py +++ b/backend/app/models/orders/order_event.py @@ -1,19 +1,8 @@ """`order_event` (S3 §3.2) — the append-only source of truth (ADR 7). -`OrderProjectionService` folds these by `seq` into `order`'s cached status/`filled_quantity`/ -`average_fill_price`. Dedupe key for `fill` events is `execution_id`, never `order_id` (ADR 7 -- -a partial fill produces many fills per order); every other event type leaves `execution_id` null. - -**`seq` assignment.** Neither S3 §3.2 nor ADR 7 specifies how `seq` values are chosen, only that -folding must tolerate gaps and out-of-order *processing* (foundation spec §10 case 4). Two -concurrent outbox workers can process a `trade_updates`-derived `accepted` and a later `fill` for -the same order in either order (`JobOutboxRepository.claim_next`'s `SKIP LOCKED` guarantees one -*row* per worker, not one *order*'s events processed in arrival order) -- an incrementing "next -available integer" counter would then durably record them backwards. Deriving `seq` instead from -the event's own logical timestamp (epoch microseconds, UTC) makes it independent of processing -order: whichever event actually happened first at the broker gets the smaller `seq`, however the -two rows are inserted. `BigInteger`, not `Integer`: epoch-microsecond values already exceed -Postgres's 32-bit `int4` range today. +`OrderProjectionService` folds these by `seq` into `order`'s cached status/fill fields. Dedupe key +for `fill` events is `execution_id`, never `order_id`. `seq` derives from the event's own logical +timestamp (epoch microseconds, UTC) so it's independent of processing order. """ from __future__ import annotations @@ -42,10 +31,7 @@ def seq_from_timestamp(ts: datetime) -> int: - """Epoch microseconds (UTC) -- the ordering key every `order_event` writer uses (module - docstring). A retried write naturally gets a fresh value, so a same-microsecond collision - (theoretical; the unique constraint below would reject it) self-heals on retry rather than - wedging the outbox row.""" + """Epoch microseconds (UTC): the ordering key every `order_event` writer uses.""" return int(ts.astimezone(UTC).timestamp() * 1_000_000) @@ -74,9 +60,7 @@ class OrderEvent(Base): SQLAlchemyEnum(OrderEventType, name="order_event_type", values_callable=enum_values), nullable=False, ) - # Set only on `fill` events -- the dedupe key (module docstring, ADR 7). Nullable so - # non-fill events (submitted/accepted/rejected/canceled/expired) simply omit it; the unique - # constraint above only ever compares the non-null values Postgres actually sees. + # Set only on `fill` events -- the dedupe key (ADR 7); other event types leave it null. execution_id: Mapped[str | None] = mapped_column(String(255), nullable=True) payload: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False) recorded_at: Mapped[datetime] = mapped_column( @@ -84,8 +68,7 @@ class OrderEvent(Base): ) -# Append-only enforcement (ADR 7, matching journal_entry/posting's precedent, S1 §6): no -# UPDATE/DELETE grant for either runtime credential. +# Append-only enforcement (ADR 7): no UPDATE/DELETE grant for either runtime credential. event.listen( OrderEvent.__table__, "after_create", @@ -94,9 +77,7 @@ class OrderEvent(Base): class OrderEventRepository(BaseRepository[OrderEvent]): - """No `customer_id_column`: `order_event` carries no customer identity of its own, matching - `journal_entry`'s precedent (S1) -- per-customer reads go through `order`, which does carry - `customer_id` and is ownership-checked at the controller before any `order_event` query.""" + """No `customer_id_column`: per-customer reads go through `order`, ownership-checked at the controller.""" append_only = True diff --git a/backend/app/models/rebalance/__init__.py b/backend/app/models/rebalance/__init__.py index a3686f4..2b8d4c1 100644 --- a/backend/app/models/rebalance/__init__.py +++ b/backend/app/models/rebalance/__init__.py @@ -12,7 +12,7 @@ class RebalanceModelsUnitOfWork(UnitOfWork): - """A `UnitOfWork` exposing the repositories S9 owns (S0 §5's documented extension mechanism).""" + """`UnitOfWork` exposing the repositories S9 owns (S0 §5).""" @cached_property def model_portfolios(self) -> ModelPortfolioRepository: diff --git a/backend/app/models/rebalance/customer_model_assignment.py b/backend/app/models/rebalance/customer_model_assignment.py index 0801bb0..1b8ce17 100644 --- a/backend/app/models/rebalance/customer_model_assignment.py +++ b/backend/app/models/rebalance/customer_model_assignment.py @@ -1,10 +1,5 @@ -"""`customer_model_assignment` (S9 §3.3) — one active model per customer at a time (FR-7), so -`customer_id` is both the primary key and the uniqueness constraint, matching -`customer_cash_lock`'s identical "one row per customer" shape (S1 §3.5). Reassigning a customer to -a different model overwrites this row rather than appending a history — model-change history -(who was assigned what, when, before this) is not part of v1's schema, matching S9 §8 item 1's own -scoping: "the *next* scheduled run evaluates against whatever model is currently assigned," with no -requirement to remember what was assigned before. +"""`customer_model_assignment` (S9 §3.3) — one active model per customer at a time (FR-7); +`customer_id` is the primary key. Reassigning overwrites this row rather than appending history. """ from __future__ import annotations @@ -36,8 +31,7 @@ class CustomerModelAssignment(Base): assigned_at: Mapped[date] = mapped_column(Date, nullable=False) -# S0 §7.3's role-aware tenant-isolation RLS policy (ADR 17) -- `customer_model_assignment` carries -# a native `customer_id` (its own primary key), same shape as `customer_cash_lock`. +# Role-aware tenant-isolation RLS policy (S0 §7.3, ADR 17). event.listen( CustomerModelAssignment.__table__, "after_create", @@ -78,8 +72,7 @@ def get_by_customer(self, customer_id: uuid.UUID) -> CustomerModelAssignment | N ) def upsert(self, assignment: CustomerModelAssignment) -> CustomerModelAssignment: - """Assign or reassign (S9 §3.3's "one active model per customer" -- overwrite, not a - history table, per this module's own docstring).""" + """Assign or reassign: overwrite, not a history table (S9 §3.3).""" existing = self.get_by_customer(assignment.customer_id) if existing is None: self.add(assignment) @@ -89,11 +82,7 @@ def upsert(self, assignment: CustomerModelAssignment) -> CustomerModelAssignment return existing def list_all(self) -> list[CustomerModelAssignment]: - """Every assigned customer, admin/worker-role only -- `MonthlyRebalanceJob`'s (S9 §7) - "for each customer with an assigned model_portfolio" driver query. Deliberately - unscoped -- the job itself runs as `SessionRole.ADMIN`, which `_tenant_scoped` already - exempts from the per-customer filter (matching `DailyValuationJob`'s own admin-role - cross-customer query, `_securities_with_positions`).""" + """Every assigned customer; admin/worker-role only (`MonthlyRebalanceJob`'s driver query, S9 §7).""" return self.session.query(CustomerModelAssignment).all() diff --git a/backend/app/models/rebalance/model_portfolio.py b/backend/app/models/rebalance/model_portfolio.py index a94ed87..97e2fc5 100644 --- a/backend/app/models/rebalance/model_portfolio.py +++ b/backend/app/models/rebalance/model_portfolio.py @@ -1,7 +1,5 @@ """`model_portfolio` (S9 §3.1) — one of exactly four (FR-7) model portfolios a customer can be -assigned to. Model portfolio *versioning* (more than one active version per model at a time) is -explicitly out of v1 scope (S9 §3.1) — this schema assumes exactly one active row per logical -model, so `is_active` is a plain flag, not a version chain. +assigned to. Versioning is out of v1 scope; `is_active` is a plain flag, not a version chain. """ from __future__ import annotations @@ -31,8 +29,7 @@ class ModelPortfolio(Base): class ModelPortfolioRepository(BaseRepository[ModelPortfolio]): - """No `customer_id_column`: a model portfolio is not tenant-scoped — every customer can be - assigned to the same one (matching `Security`'s precedent, S4 §3.3).""" + """No `customer_id_column`: a model portfolio is not tenant-scoped.""" def __init__(self, uow: UnitOfWork) -> None: super().__init__(uow, entity=ModelPortfolio) diff --git a/backend/app/models/rebalance/target_weight.py b/backend/app/models/rebalance/target_weight.py index b051338..795eb52 100644 --- a/backend/app/models/rebalance/target_weight.py +++ b/backend/app/models/rebalance/target_weight.py @@ -1,15 +1,6 @@ -"""`target_weight` (S9 §3.2) — one row per `(model_portfolio, security)`, weighted to sum to -exactly `1.0` for every `model_portfolio_id`. - -That sum-to-one invariant is a **deferred constraint trigger**, the same mechanism and the same -reasoning as S1 §3.4's money-sum-to-zero trigger (`app/models/ledger/posting.py`): it is a -*cross-row* invariant a plain `CHECK` cannot express (Postgres has no cross-row `CHECK`), and it -must be deferred to `COMMIT` rather than firing per-row, because populating a model's weights is -itself several inserts within one transaction — the sum is only ever meaningful once every row for -that `model_portfolio_id` has been written. Deleting the last row of a model (leaving `SUM = 0`) is -rejected the same way: a model portfolio with any target weights at all must sum to `1.0`, full -stop, so removing weights without replacing them in the same transaction is exactly as invalid as -never having balanced in the first place. +"""`target_weight` (S9 §3.2) — one row per `(model_portfolio, security)`, summing to `1.0` per +`model_portfolio_id`. Sum-to-one is a deferred constraint trigger (same mechanism as S1 §3.4's +money-sum-to-zero trigger), since Postgres has no cross-row `CHECK`. """ from __future__ import annotations @@ -44,8 +35,7 @@ class TargetWeight(Base): security_id: Mapped[uuid.UUID] = mapped_column( UUID(as_uuid=True), ForeignKey("security.id"), nullable=False ) - # A ratio, not a money/units/price dimension (ADR 16) -- ADR 16's value objects deliberately - # don't cover this, matching `sub_period_return.return_pct`'s identical precedent. + # A ratio, not a money/units/price dimension (ADR 16). weight_pct: Mapped[Decimal] = mapped_column(Numeric(5, 4), nullable=False) diff --git a/backend/app/models/reconciliation/__init__.py b/backend/app/models/reconciliation/__init__.py index b5039a7..6deff3f 100644 --- a/backend/app/models/reconciliation/__init__.py +++ b/backend/app/models/reconciliation/__init__.py @@ -1,11 +1,7 @@ """Reconciliation aggregates (S7) -- the custodian-file import log and the break register. -`ReconciliationUnitOfWork` exposes S7's own two repositories (S0 §5's documented extension -mechanism), the same shape as `LedgerUnitOfWork`/`MarketDataUnitOfWork`/`OpsUnitOfWork`. The -composed `UnitOfWork` `ReconciliationService`/`MorningReconciliationJob`/the admin breaks -controller actually use -- combining this with `LedgerUnitOfWork` (positions/cash) and -`MarketDataUnitOfWork` (the trading calendar) -- lives in `app/services/reconciliation/uow.py`, -matching `ValuationUnitOfWork`'s precedent for the identical shape of problem. +`ReconciliationUnitOfWork` exposes S7's own repositories (S0 §5); the composed `UnitOfWork` +services actually use lives in `app/services/reconciliation/uow.py`. """ from __future__ import annotations diff --git a/backend/app/models/reconciliation/custodian_file_row.py b/backend/app/models/reconciliation/custodian_file_row.py index a9d9156..abdf465 100644 --- a/backend/app/models/reconciliation/custodian_file_row.py +++ b/backend/app/models/reconciliation/custodian_file_row.py @@ -1,9 +1,6 @@ -"""`custodian_file_row` (S7 §5.1) — one row per source row of one morning's three custodian files, -preserved verbatim before any comparison logic runs (S7 §3's event-intake-style principle: persist -the raw fact before deriving anything from it). - -Append-only: a custodian file delivery is a point-in-time fact, never corrected in place — a -re-delivered or corrected file is a new `import_batch_id`, not an `UPDATE` of a prior one. +"""`custodian_file_row` (S7 §5.1) — one row per source row of one morning's custodian files, +preserved verbatim before any comparison logic runs (S7 §3). Append-only; a re-delivered or +corrected file is a new `import_batch_id`, never an `UPDATE`. """ from __future__ import annotations @@ -48,16 +45,14 @@ class CustodianFileRow(Base): ) raw_row: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False) import_batch_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), nullable=False) - # FR-33's "clearly labelled" requirement enforced structurally (S7 §9), not just by naming - # convention on whichever adapter produced the row. + # FR-33's "clearly labelled" requirement enforced structurally (S7 §9). is_simulated: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False) imported_at: Mapped[datetime] = mapped_column( DateTime(timezone=True), nullable=False, server_default=func.now() ) -# Append-only enforcement (S7 §3): a custodian file delivery is a preserved point-in-time fact, -# same posture as journal_entry/posting/daily_close. +# Append-only enforcement (S7 §3): a preserved point-in-time fact. event.listen( CustodianFileRow.__table__, "after_create", @@ -68,10 +63,7 @@ class CustodianFileRow(Base): class CustodianFileRowRepository(BaseRepository[CustodianFileRow]): - """No `customer_id_column`: a single row may or may not carry a customer identity depending - on `file_type` (a cash-only transaction row has none), and the table as a whole is an - operational import log, not tenant-scoped data (matching `InboundEventRepository`'s - precedent).""" + """No `customer_id_column`: an operational import log, not tenant-scoped data.""" append_only = True diff --git a/backend/app/models/reconciliation/reconciliation_break.py b/backend/app/models/reconciliation/reconciliation_break.py index 734288f..56a68cb 100644 --- a/backend/app/models/reconciliation/reconciliation_break.py +++ b/backend/app/models/reconciliation/reconciliation_break.py @@ -1,17 +1,9 @@ """`reconciliation_break` (S7 §5.2) — one row per detected discrepancy between Trueup's internal state and one morning's custodian file. -**Append-only for the identifying facts, single controlled transition for resolution** — the same -shape `settlement_obligation` already establishes (S1 §4, ADR 2): `break_type`, `customer_id`, -`expected`, `actual`, `opened_at`, and `import_batch_id` never change once written (S7 §5.2); only -`status`/`resolved_at`/`resolved_by`/`resolution_note` transition, and exactly once, `open -> -resolved`. A `BEFORE UPDATE` trigger enforces both halves at the database, backstopping the -application-layer checks in `ReconciliationBreakRepository.resolve()`. - -**FR-44 as a `CHECK` constraint, not only application validation** (S7 §11): `resolved_by` must be -non-null whenever `status = 'resolved'` — there is no system-generated resolution path, by design, -and a `resolved` row with no `resolved_by` is itself a bug, not a valid state the database should -ever accept. +Append-only for the identifying facts; `status`/`resolved_*` transition exactly once, `open -> +resolved`, via a `BEFORE UPDATE` trigger (same shape as `settlement_obligation`, S1 §4, ADR 2). +FR-44: `resolved_by` non-null whenever `status = 'resolved'` is a `CHECK` constraint (S7 §11). """ from __future__ import annotations @@ -69,9 +61,8 @@ class ReconciliationBreak(Base): ), nullable=False, ) - # Nullable only for a break with no single-customer attribution (S7 §5.2: rare, e.g. a - # malformed file row). No FK: `customer` is a cross-aggregate reference the same way - # `account.customer_id`/`order.customer_id` predate a formal cross-schema FK convention. + # Nullable only for a break with no single-customer attribution (S7 §5.2). No FK: predates a + # formal cross-schema FK convention. customer_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), nullable=True) expected: Mapped[dict[str, Any] | None] = mapped_column(JSONB, nullable=True) actual: Mapped[dict[str, Any] | None] = mapped_column(JSONB, nullable=True) @@ -87,13 +78,11 @@ class ReconciliationBreak(Base): server_default=ReconciliationBreakStatus.OPEN.value, ) resolved_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True) - # A human actor id (adviser/admin) -- FR-44: there is no system-generated resolution path. - # No FK: `staff` predates a formal cross-schema FK convention, matching `customer_id` above. + # A human actor id (adviser/admin) -- FR-44: no system-generated resolution path. No FK. resolved_by: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), nullable=True) resolution_note: Mapped[str | None] = mapped_column(String, nullable=True) - # Groups this break back to the custodian_file_row rows from the same morning's import (S7 - # §5.2) -- not a formal FK since custodian_file_row has no distinct "batch" entity of its own, - # only a shared import_batch_id tag on many rows. + # Groups this break back to the custodian_file_row rows from the same morning's import + # (S7 §5.2). import_batch_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), nullable=False) @@ -141,8 +130,7 @@ class ReconciliationBreak(Base): ), ) -# DELETE is revoked, matching settlement_obligation's append-only-except-one-transition posture; -# UPDATE stays granted for the one-time open -> resolved transition the trigger above polices. +# DELETE revoked; UPDATE stays granted for the one-time open -> resolved transition above. event.listen( ReconciliationBreak.__table__, "after_create", @@ -151,9 +139,8 @@ class ReconciliationBreak(Base): ), ) -# S0 §7.3's role-aware tenant-isolation RLS policy (ADR 17): a customer session sees only breaks -# attributed to it; a break with no customer attribution (customer_id IS NULL) is visible only to -# adviser/admin, matching a house account's exclusion on `account.customer_id IS NULL`. +# Role-aware tenant-isolation RLS policy (S0 §7.3, ADR 17); a break with no customer attribution +# is visible only to adviser/admin. event.listen( ReconciliationBreak.__table__, "after_create", @@ -179,15 +166,13 @@ class ReconciliationBreak(Base): class AlreadyResolvedError(RuntimeError): - """A `resolved` break was passed to `resolve()` again -- status transitions exactly once + """A `resolved` break was passed to `resolve()` again; status transitions exactly once (S7 §5.2).""" class ReconciliationBreakRepository(BaseRepository[ReconciliationBreak]): - """No `customer_id_column`: `customer_id` is nullable here (S7 §5.2), and the adviser-facing - break screen (S7 §8, consumed by S8) is deliberately cross-customer by design, the same shape - as `AccountRepository`'s adviser/admin branch -- a customer session still gets RLS-level - scoping from the policy above, this repository does not additionally restrict it.""" + """No `customer_id_column`: `customer_id` is nullable (S7 §5.2); the break screen is + deliberately cross-customer by design (S7 §8).""" def __init__(self, uow: UnitOfWork) -> None: super().__init__(uow, entity=ReconciliationBreak) @@ -196,8 +181,7 @@ def get_by_id(self, break_id: uuid.UUID) -> ReconciliationBreak | None: return self.session.query(ReconciliationBreak).filter_by(id=break_id).first() def list_open(self) -> list[ReconciliationBreak]: - """Sorted oldest-`opened_at`-first (S7 §7: `age` descending), so the longest-open break is - always first.""" + """Sorted oldest-`opened_at`-first (S7 §7): the longest-open break is always first.""" return list( self.session.query(ReconciliationBreak) .filter_by(status=ReconciliationBreakStatus.OPEN) @@ -206,8 +190,8 @@ def list_open(self) -> list[ReconciliationBreak]: ) def list_open_for_customer(self, customer_id: uuid.UUID) -> list[ReconciliationBreak]: - """S8 §6 edge case 2: `GET /admin/customers/` must surface a customer's own open - break prominently, oldest first (same ordering as `list_open`).""" + """`GET /admin/customers/` surfaces a customer's own open break, oldest first + (S8 §6).""" return list( self.session.query(ReconciliationBreak) .filter_by(status=ReconciliationBreakStatus.OPEN, customer_id=customer_id) diff --git a/backend/app/services/admin/uow.py b/backend/app/services/admin/uow.py index a35faad..9439796 100644 --- a/backend/app/services/admin/uow.py +++ b/backend/app/services/admin/uow.py @@ -1,17 +1,4 @@ -"""`AdminUnitOfWork` — S8's admin surface (`/admin/customers`, `/admin/customers/`, -`/admin/customers//fees`) reads across S1 (ledger/balance), S2 (customer identity), S4 (market -data, for `ValuationService`), S6 (published snapshots), S7 (reconciliation breaks), and S10 -(fees) — so this composes `FeesUnitOfWork` (which already carries `IdentityUnitOfWork` and -`RestatementUnitOfWork`, itself `ValuationUnitOfWork` + `RestatementModelsUnitOfWork`) with S7's -own model-only mixin, the identical multiple-inheritance shape every other cross-aggregate -consumer in this codebase already uses (S0 §5's documented extension mechanism). - -Composing `FeesUnitOfWork` rather than duplicating its accessors is what lets -`GET /admin/customers/` call the *same* `ValuationService.value_book` code path -`GET /valuation/balance` does (S8 §6 edge case 4's no-drift requirement) and -`GET /admin/customers//fees` call the *same* fee-summary assembly `GET /fees` does, on one -`UnitOfWork` rather than two independently-implemented aggregations. -""" +"""Admin surface UoW (S8): composes `FeesUnitOfWork` with S7's reconciliation mixin.""" from __future__ import annotations diff --git a/backend/app/services/agent_surface/__init__.py b/backend/app/services/agent_surface/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/services/agent_surface/uow.py b/backend/app/services/agent_surface/uow.py new file mode 100644 index 0000000..708d50d --- /dev/null +++ b/backend/app/services/agent_surface/uow.py @@ -0,0 +1,14 @@ +"""Agent surface UoW (S13): composes `RebalanceUnitOfWork`, reconciliation, and ops mixins.""" + +from __future__ import annotations + +from app.models.ops import OpsUnitOfWork +from app.models.reconciliation import ReconciliationUnitOfWork as ReconciliationModelsUnitOfWork +from app.services.rebalance.uow import RebalanceUnitOfWork + + +class AgentSurfaceUnitOfWork(RebalanceUnitOfWork, ReconciliationModelsUnitOfWork, OpsUnitOfWork): + pass + + +__all__ = ["AgentSurfaceUnitOfWork"] diff --git a/backend/app/services/chat/chat_audit_service.py b/backend/app/services/chat/chat_audit_service.py index 2850054..c64e470 100644 --- a/backend/app/services/chat/chat_audit_service.py +++ b/backend/app/services/chat/chat_audit_service.py @@ -1,14 +1,4 @@ -"""`ChatAuditService` (S11 §3/§5.2 step 4, FR-53) — writes one `chat_tool_call` row per tool -invocation, committed independently of the turn's own outcome. - -**Why this owns a `UnitOfWork` factory, not a single injected `UnitOfWork`.** S11 §5.2 step 4 is -explicit: "each tool call is recorded ... as it happens, not batched at the end — so a turn that -fails partway through still leaves an audit trail." A single `UnitOfWork` per HTTP request (S0 -§5's normal shape) cannot honor that -- if the turn's own transaction later rolls back, every -audit row written on it rolls back too. Each `record_tool_call()` call therefore opens, commits, -and closes its own short-lived `UnitOfWork` via the injected factory, so an audit write survives -independently of whatever happens for the rest of the turn. -""" +"""Writes one `chat_tool_call` row per tool invocation, each in its own committed UoW (S11 §5.2).""" from __future__ import annotations @@ -30,7 +20,7 @@ class ChatAuditUnitOfWork(Protocol): - """The structural dependency this service needs -- `ChatUnitOfWork` satisfies it.""" + """Satisfied by `ChatUnitOfWork`.""" @property def chat_tool_calls(self) -> ChatToolCallRepository: ... diff --git a/backend/app/services/chat/chat_orchestration_service.py b/backend/app/services/chat/chat_orchestration_service.py index 7a574b5..a358a95 100644 --- a/backend/app/services/chat/chat_orchestration_service.py +++ b/backend/app/services/chat/chat_orchestration_service.py @@ -1,17 +1,7 @@ -"""`ChatOrchestrationService` (S11 §5.2) — builds the agent, runs one turn, drives the SSE stream. - -Split into two phases so the controller can reject a turn with an ordinary JSON error response, -never a half-opened SSE stream (S11 §5.3's "rejected before any model call, with a clear -customer-facing message" applies to both the usage cap and the concurrency lock): - -- `begin_turn()` — synchronous. Usage-cap check (step 1), lock acquisition (step 2), persists the - user's message, and creates the assistant's placeholder `chat_message` row (empty `content`) so - every tool call the turn makes has something to attach to (see `app/models/chat/chat_message.py`'s - module docstring for why). Raises `DailyQueryCapExceededError`/`TurnAlreadyInProgressError` - before anything else happens. -- `stream_turn()` — a generator. Runs the agent via `LlmAgentPort` (step 3), yields token events as - they arrive, and on completion finalizes the placeholder message and releases the session lock - (step 5) in a `finally`, so a turn that raises mid-stream still unlocks the session. +"""Builds the agent, runs one chat turn, drives the SSE stream (S11 §5.2). + +`begin_turn()` checks the usage cap and lock synchronously; `stream_turn()` streams the +agent's response and releases the lock in a `finally`. """ from __future__ import annotations @@ -64,8 +54,7 @@ class TurnAlreadyInProgressError(Exception): - """S11 §5.3: reject a second concurrent turn on the same session with a clear "still - answering" response, rather than running two agent loops against one conversation.""" + """Raised to reject a second concurrent turn on the same session (S11 §5.3).""" @dataclass(frozen=True, slots=True) @@ -77,7 +66,7 @@ class BegunTurn: class ChatOrchestrationUnitOfWork(Protocol): - """The structural dependency `begin_turn`/finalization need -- `ChatUnitOfWork` satisfies it.""" + """Satisfied by `ChatUnitOfWork`.""" @property def chat_sessions(self) -> ChatSessionRepository: ... diff --git a/backend/app/services/chat/chat_usage_limiter.py b/backend/app/services/chat/chat_usage_limiter.py index dc8a1ae..db32575 100644 --- a/backend/app/services/chat/chat_usage_limiter.py +++ b/backend/app/services/chat/chat_usage_limiter.py @@ -1,8 +1,4 @@ -"""`ChatUsageLimiter` (S11 §5.2 step 1, NFR-16) — the per-customer daily query cap, independent of -the per-turn tool-iteration cap (`ChatOrchestrationService` enforces that one directly against the -configured `chat_max_tool_iterations`). Checked before any model call, since the cap is about total -tool-call cost across a whole day, not just the current turn. -""" +"""Per-customer daily chat query cap, checked before any model call (S11 §5.2 step 1, NFR-16).""" from __future__ import annotations @@ -20,7 +16,7 @@ def count_for_customer_since(self, customer_id: uuid.UUID, since: datetime) -> i class ChatUsageLimiterUnitOfWork(Protocol): - """The structural dependency this service needs -- `ChatUnitOfWork` satisfies it.""" + """Satisfied by `ChatUnitOfWork`.""" @property def chat_messages(self) -> _ChatMessageRepoProtocol: ... @@ -34,8 +30,7 @@ def __exit__( class DailyQueryCapExceededError(Exception): - """Raised by `check()` when the customer has already spent today's query cap (S11 §5.3: - "Turn is rejected before any model call, with a clear customer-facing message").""" + """Raised by `check()` when the customer has already spent today's query cap (S11 §5.3).""" class ChatUsageLimiter: @@ -46,8 +41,7 @@ def __init__( self._daily_query_cap = daily_query_cap def check(self, customer_id: uuid.UUID, *, now: datetime | None = None) -> None: - """Raises `DailyQueryCapExceededError` if `customer_id` has already sent - `daily_query_cap` user messages in the trailing 24 hours; otherwise returns silently.""" + """Raises `DailyQueryCapExceededError` if the cap was hit in the trailing 24 hours.""" since = (now or datetime.now(UTC)) - timedelta(hours=24) with self._uow_factory() as uow: count = uow.chat_messages.count_for_customer_since(customer_id, since) diff --git a/backend/app/services/chat/read_only_sql_executor.py b/backend/app/services/chat/read_only_sql_executor.py index e6f9f56..a4acc77 100644 --- a/backend/app/services/chat/read_only_sql_executor.py +++ b/backend/app/services/chat/read_only_sql_executor.py @@ -1,22 +1,4 @@ -"""`ReadOnlySqlExecutor` (ADR 19 §4.2/§4.4) — the only code that opens a connection under -`DbRole.CHAT`. Reuses `UnitOfWork` itself for that connection (rather than a raw `Engine`): opening -`UnitOfWork(customer_id=..., role=SessionRole.CUSTOMER, db_role=DbRole.CHAT)` already runs the -`set_config('app.role', ...)`/`set_config('app.customer_id', ...)` calls every other customer-scoped -connection gets (`app/core/uow.py`) — the curated views' own tenant predicate -(`app/models/chat/curated_views.py`) depends on exactly those two GUCs, so this executor needs no -GUC-setting logic of its own. - -Two independent, server-side controls wrap every query, per ADR 19 §4.4, regardless of what the -validated query itself asks for: - -- `SET LOCAL statement_timeout` (transaction-scoped, gone the instant this short-lived - `UnitOfWork` closes). -- The validated query is wrapped as `SELECT * FROM () AS sub LIMIT :row_cap` before - execution. - -A validator rejection, a timeout, or any other execution failure all return a structured -`SqlToolOutcome` (S11 §5.3) -- never a raw Postgres error string reaches the caller (OWASP A05). -""" +"""The only code that opens a DB connection under `DbRole.CHAT`; enforces timeout + row cap (ADR 19 §4.2/§4.4).""" from __future__ import annotations @@ -51,8 +33,7 @@ def __init__(self, *, statement_timeout_ms: int = 3000, row_cap: int = 1000) -> self._row_cap = row_cap def describe_schema(self, customer_id: uuid.UUID) -> str: - """`get_database_schema` (S11 §3) -- reads live column metadata for the curated views - rather than a hand-maintained string, so the two can never drift apart.""" + """`get_database_schema` (S11 §3) -- reads live curated-view column metadata.""" with UnitOfWork( customer_id=customer_id, role=SessionRole.CUSTOMER, db_role=DbRole.CHAT ) as uow: @@ -72,17 +53,14 @@ def describe_schema(self, customer_id: uuid.UUID) -> str: ) def execute(self, sql: str, *, customer_id: uuid.UUID) -> SqlToolOutcome: - """`execute_read_only_sql` (S11 §3). Validates first (ADR 19 §4.3); a rejection never - opens a connection at all.""" + """`execute_read_only_sql` (S11 §3). Validates first (ADR 19 §4.3).""" validation = validate_query(sql) if not validation.ok or validation.normalized_sql is None: return SqlToolOutcome( status="validator_rejected", message=validation.reason or "query rejected" ) - # Not a bind parameter: `validation.normalized_sql` is parser-validated, re-serialized SQL - # text (ADR 19 §4.3), not a value a placeholder could carry -- the security control here - # is the upstream validator + `chat_readonly`'s own grants, not query parameterization. + # Not a bind param: normalized_sql is parser-validated per ADR 19 §4.3. wrapped_sql = ( f"SELECT * FROM ({validation.normalized_sql}) AS sub LIMIT {self._row_cap}" # noqa: S608 # nosec B608 ) diff --git a/backend/app/services/chat/sql_tool_validator.py b/backend/app/services/chat/sql_tool_validator.py index d2f28d7..d046c08 100644 --- a/backend/app/services/chat/sql_tool_validator.py +++ b/backend/app/services/chat/sql_tool_validator.py @@ -1,26 +1,7 @@ -"""`sql_tool_validator` (S11 §4.3, ADR 19) — the static query-shape check run before -`execute_read_only_sql` ever opens a database connection. Pure function, no I/O: parses with a real -SQL parser (`sqlglot`, Postgres dialect) rather than string matching, which is trivially defeated by -whitespace/comment tricks (ADR 19's own reasoning). - -Five checks, in order, each returning a structured rejection reason on failure (never a raw parser -exception -- `ValidationResult.reason` is always customer/agent-safe): - -1. Parses at all. -2. Exactly one statement (rejects a trailing `;` followed by more SQL). -3. That statement is a `SELECT` (a plain `Select`, or a `UNION`/`INTERSECT`/`EXCEPT` of them -- - still purely read-only; every DML/DDL class fails this check at the AST level). -4. Every referenced relation is in `CURATED_VIEW_NAMES` -- the **same** allow-list constant - `curated_views.py`'s migration SQL grants `chat_readonly`, imported from one place so the two - cannot silently diverge (ADR 19 §4.3 point 4). A CTE's own alias is excluded from this check -- - it names a local result set, not a relation to authorize. -5. Every function call is on `_ALLOWED_FUNCTIONS` (aggregate/date functions only) -- closes off - `pg_sleep`, `dblink`, and anything else with no legitimate role in a reporting query. - -On success, `ValidationResult.normalized_sql` is the **re-serialized** statement, not the caller's -original text -- comments are dropped and formatting is canonicalized in the process, which is a -second, incidental defense against a comment-based obfuscation trick surviving into what actually -executes. `ChatOrchestrationService` executes `normalized_sql`, never the raw input. +"""Static query-shape check before `execute_read_only_sql` opens a connection (S11 §4.3, ADR 19). + +Pure function: parses with `sqlglot`, rejects multi-statement/non-SELECT/uncurated +relations/disallowed functions, and returns the re-serialized SQL on success. """ from __future__ import annotations diff --git a/backend/app/services/chat/uow.py b/backend/app/services/chat/uow.py index 4e0bb30..15071eb 100644 --- a/backend/app/services/chat/uow.py +++ b/backend/app/services/chat/uow.py @@ -1,12 +1,4 @@ -"""`ChatUnitOfWork` — S11's own aggregate (`chat_session`/`chat_message`/`chat_tool_call`), the -same thin composition shape `RestatementUnitOfWork` uses (S0 §5's documented extension mechanism). - -Runs under `DbRole.APP` (the default), like every other customer-facing feature's `UnitOfWork` -- -these three tables are ordinary application data the web API role already has full CRUD on. This -is entirely separate from `DbRole.CHAT`, which `ChatOrchestrationService` uses for a raw, -short-lived connection dedicated to running the LLM's *validated* SQL against the curated views -(ADR 19) -- that connection never goes through the ORM or this `UnitOfWork` at all. -""" +"""UoW for S11's chat aggregate (`chat_session`/`chat_message`/`chat_tool_call`). Runs under `DbRole.APP`.""" from __future__ import annotations diff --git a/backend/app/services/fees/_shared.py b/backend/app/services/fees/_shared.py index b58dc0a..6bfe639 100644 --- a/backend/app/services/fees/_shared.py +++ b/backend/app/services/fees/_shared.py @@ -1,9 +1,4 @@ -"""Account-bootstrap and event-synthesis helpers for S10's services, following -`app.services.lots._shared`'s exact precedent (`get_or_create_customer_account`/ -`get_or_create_house_account`/`record_inbound_event`) -- duplicated locally per this codebase's own -established convention (`DepositService`, `WashSaleService` each keep their own copy) rather than -importing across service packages. -""" +"""Account-bootstrap and event-synthesis helpers for S10's services.""" from __future__ import annotations diff --git a/backend/app/services/fees/dunning_service.py b/backend/app/services/fees/dunning_service.py index 45db843..4bbbdaf 100644 --- a/backend/app/services/fees/dunning_service.py +++ b/backend/app/services/fees/dunning_service.py @@ -1,17 +1,6 @@ -"""`DunningService` (S10 §5, ADR 10, FR-48) — the retry/backoff/exhaustion state machine behind a -failed fee charge. +"""Retry/backoff/exhaustion state machine for a failed fee charge (S10 §5, ADR 10, FR-48). -Deliberately owns only the *bookkeeping* (attempt counting, backoff scheduling, the -`retrying -> exhausted` transition) -- the actual "call Stripe again" step is -`FeeChargeService.attempt_charge`, reused unchanged for both the first attempt and every retry -(`DunningRetryJob` calls it directly). Splitting it this way avoids a circular import -(`FeeChargeService` already depends on this module to start dunning on a first failure) and matches -this codebase's own precedent of a state-machine service that never itself performs the I/O its -transitions react to (`AccountApprovalService` never calls Stripe/Plaid directly either). - -Exponential backoff, doubling each attempt from a configurable base -- a defensible engineering -default (`DUNNING_BACKOFF_BASE_HOURS`), flagged for business/compliance review before go-live, same -posture as `KYC_MAX_ATTEMPTS`/the deposit caps (`DECISION-LOG.md`'s Assumptions table). +Owns bookkeeping only; `FeeChargeService.attempt_charge` performs the actual retry call. """ from __future__ import annotations @@ -30,8 +19,7 @@ def compute_backoff(attempt_number: int, *, base_hours: int) -> timedelta: - """`attempt_number` is 1-indexed (the attempt that just failed); the delay before the *next* - attempt doubles each time: `base_hours * 2**(attempt_number - 1)`.""" + """1-indexed `attempt_number`; delay doubles each time: `base_hours * 2**(attempt_number - 1)`.""" if attempt_number < 1: raise ValueError("attempt_number must be at least 1") return timedelta(hours=base_hours * (2 ** (attempt_number - 1))) @@ -52,9 +40,7 @@ def __init__( self._now = now def start(self, charge: FeeCharge) -> DunningState: - """The first failure on a `fee_charge` (S10 §5: `on Stripe failure: ... DunningService. - start(fee_charge_id) -- never reverses the accrual`). `fee_charge.status` is set by the - caller (`FeeChargeService.apply_charge_failure`) before this runs.""" + """First failure on a `fee_charge` (S10 §5); never reverses the accrual.""" dunning = DunningState( fee_charge_id=charge.id, customer_id=charge.customer_id, @@ -68,10 +54,7 @@ def start(self, charge: FeeCharge) -> DunningState: return dunning def record_retry_failure(self, dunning: DunningState, charge: FeeCharge) -> None: - """A subsequent retry attempt also failed (S10 §5): bump `attempt_number`; exhaust once - `max_attempts` is reached (`fee_charge.status` moves to `dunning`, a standing, - customer-visible balance owed -- FR-48's "never silently dropped"), otherwise schedule the - next backoff.""" + """A retry attempt failed (S10 §5): bump attempt count, exhaust or reschedule backoff.""" dunning.attempt_number += 1 if dunning.attempt_number >= dunning.max_attempts: dunning.status = DunningStatus.EXHAUSTED diff --git a/backend/app/services/fees/fee_accrual_service.py b/backend/app/services/fees/fee_accrual_service.py index a09a287..e03ac65 100644 --- a/backend/app/services/fees/fee_accrual_service.py +++ b/backend/app/services/fees/fee_accrual_service.py @@ -1,18 +1,7 @@ -"""`FeeAccrualService` (S10 §4, ADR 10) — the daily posting `DailyFeeAccrualJob` calls once per -customer. +"""Daily fee-accrual posting `DailyFeeAccrualJob` calls once per customer (S10 §4, ADR 10). -Actual/365 day-count (S10 §4's own defended sub-decision): the daily fee is -`gain_above_hwm x FEE_RATE_PCT x (1/365)`, computed as one `Money * Decimal` multiplication -(`gain * (fee_rate_pct / 365)`) rather than two chained `Money` multiplications, to take only one -rounding step instead of two. - -The accrual posting and the high-water-mark update happen in the same transaction, and the -`fee_accrual` insert is wrapped in a `SAVEPOINT` (`session.begin_nested()`, the same pattern -`InboundEventRepository.record()` already establishes for a dedupe-by-unique-constraint check): a -second full run of the job for a date already accrued hits `fee_accrual`'s own -`UNIQUE (customer_id, accrual_date)` constraint, and that savepoint is what lets this one customer's -"already done" outcome roll back cleanly without discarding every other customer already processed -in the same job transaction (S10 §8 edge case 4). +Actual/365 day-count; accrual + HWM update run inside a `SAVEPOINT` so a duplicate-date +run for one customer rolls back cleanly without discarding the rest of the job (S10 §8 edge case 4). """ from __future__ import annotations @@ -62,15 +51,7 @@ def __init__( def accrue_for_customer( self, customer_id: uuid.UUID, accrual_date: date ) -> FeeAccrual | None: - """`None` means either the customer has no funded basis yet (nothing to accrue) or this - date was already accrued by an earlier run (S10 §8 edge case 4) -- both are legitimate - no-ops, never an error. - - The high-water-mark read is a pure, side-effect-free computation, safe to run before the - `SAVEPOINT` opens; the ratchet itself (a real mutation) is deliberately performed *inside* - the savepoint below, alongside the posting and the `fee_accrual` insert -- so that if the - insert's unique-constraint check fails, the ratchet rolls back with it instead of silently - surviving a "duplicate" outcome (S10 §4's "same transaction" requirement).""" + """`None` means no funded basis yet, or this date was already accrued (S10 §8 edge case 4).""" shadow_value = self._hwm_service.shadow_nav(customer_id, accrual_date) if shadow_value is None: return None @@ -102,9 +83,7 @@ def _post_accrual( revenue_account = get_or_create_house_account( self._uow, role=AccountRole.FEE_REVENUE_ACCRUED ) - # No natural provider event backs a scheduled job's own computation -- MARKETDATA, matching - # `CorporateActionService`'s identical precedent for an internally-derived posting with no - # raw webhook behind it (the accrual is derived from S4's TWR, itself built on market data). + # Internally-derived posting, no webhook -- source MARKETDATA (cf. CorporateActionService). event = record_inbound_event( self._uow, source=InboundEventSource.MARKETDATA, diff --git a/backend/app/services/fees/fee_charge_outbox_handler.py b/backend/app/services/fees/fee_charge_outbox_handler.py index 5b305e2..37f8222 100644 --- a/backend/app/services/fees/fee_charge_outbox_handler.py +++ b/backend/app/services/fees/fee_charge_outbox_handler.py @@ -1,12 +1,4 @@ -"""`FeeChargeOutboxHandler` (S10 §5, ADR 10) — the outbox task handler for `"charge_fee"`. - -The actual Stripe call happens with **no database transaction open** (S0 §5's no-I/O-in-transaction -rule, matching `OutboxWorker.drain_once`'s own doc: "slow provider I/O never holds the row lock or -database transaction open"): `charge_fee` reads the pending charge and its payment method in one -short transaction, calls the provider with the transaction already committed and closed, then -applies the result in a second, fresh transaction. `DunningRetryJob` calls `charge_fee` directly -for the same reason -- a retry is exactly the same three-phase operation as the first attempt. -""" +"""Outbox task handler for `"charge_fee"` (S10 §5, ADR 10). Stripe call runs with no DB transaction open.""" from __future__ import annotations @@ -27,9 +19,7 @@ class NoPaymentMethodError(RuntimeError): - """The customer has no `payment_method` attached -- the charge cannot even be attempted. Left - to propagate so the outbox retries it (a payment method may be attached before the next - attempt) rather than silently dropping the charge.""" + """No `payment_method` attached; propagates so the outbox retries later.""" class UnregisteredFeeOutboxTaskError(RuntimeError): diff --git a/backend/app/services/fees/fee_charge_service.py b/backend/app/services/fees/fee_charge_service.py index 965a7ac..903d6b3 100644 --- a/backend/app/services/fees/fee_charge_service.py +++ b/backend/app/services/fees/fee_charge_service.py @@ -1,24 +1,6 @@ -"""`FeeChargeService` (S10 §5, ADR 10) — creates a billing period's pending charge (no I/O), -applies the Stripe outcome once the outbox has actually called the provider, and posts the -success-side ledger entry. - -**Ledger construction for a successful charge, a judgment call this module documents rather than -guesses at silently.** ADR 10's prose ("debit fee_revenue_accrued / credit fee_revenue_collected, -and clear fees_accrued_payable") names three accounts, but a single zero-sum journal entry cannot -move all three by the same magnitude with only two legal signs (an odd count of equal-magnitude -legs can never sum to zero). This implementation clears `fees_accrued_payable` against -`fee_revenue_collected` -- the literal "clear the liability, recognize the cash now collected" pair --- and leaves `fee_revenue_accrued` untouched at charge time, standing permanently as "gross fees -ever accrued to date" (mirroring how `fees_expense`/`dividend_income` already behave as lifetime -accumulators elsewhere in S1). `fee_revenue_collected` is the parallel "gross ever collected" -accumulator; the difference between the two, at any point, is what `fees_accrued_payable` should -show as still outstanding -- a cross-checkable invariant, not an enforced one. Flagged in the -fee-engineer close-out report as a deviation from the ADR's literal wording, not a silent guess. - -**Locks to the as-published watermark, never a live figure (FR-47).** `_ensure_published` calls -`SnapshotService.publish` only if no snapshot already exists for this exact period -- mirroring S6 -§7's own rule against a caller supplying an arbitrary timestamp -- so the same billing period is -never published twice with two different watermarks by two runs of this job. +"""Creates a billing period's pending charge, applies the Stripe outcome, posts the ledger entry (S10 §5, ADR 10). + +Locks to the as-published watermark, never a live figure (FR-47). """ from __future__ import annotations @@ -66,22 +48,15 @@ def __init__( self._dunning_max_attempts = dunning_max_attempts self._now = now - # --- MonthlyFeeChargeJob's per-customer step (no provider I/O) ----------------------------- + # MonthlyFeeChargeJob's per-customer step (no provider I/O). def create_pending_charge( self, customer_id: uuid.UUID, *, period_start: date, period_end: date ) -> FeeCharge | None: - """`None` when the period's `total_accrued` is zero -- a $0 Stripe charge is never - created (`DECISION-LOG.md`'s general guard), whether that's because `FEE_RATE_PCT` is - `0.0` or a customer genuinely had zero gain -- or when this period's charge already exists - (idempotent re-run of the job). - - The read-then-insert below is a courtesy fast path, not the actual idempotency guarantee - (F5 fix, S0 §10.1 audit): two concurrent or retried job runs could both pass the `existing - is None` check before either commits. `uq_fee_charge_customer_period` is the real - backstop -- the insert runs inside a `SAVEPOINT` so a unique-violation there rolls back - only the attempted duplicate, then re-reads the row the other run just committed, matching - `FeeAccrualService.accrue_for_customer`'s own established pattern for the identical race. + """`None` when `total_accrued` is zero, or this period's charge already exists. + + Read-then-insert is a fast path; `uq_fee_charge_customer_period` + a `SAVEPOINT` are the + real idempotency backstop against a concurrent duplicate (F5 fix, S0 §10.1 audit). """ existing = self._uow.fee_charges.get_for_period( customer_id, period_start=period_start, period_end=period_end @@ -129,7 +104,7 @@ def _ensure_published( snapshot = SnapshotService(self._uow).publish(customer_id, period_start, period_end) return snapshot.publish_watermark - # --- Applying a provider outcome -- called from both the outbox handler and the webhook ----- + # Applying a provider outcome; called from both the outbox handler and the webhook. def apply_charge_success(self, fee_charge_id: uuid.UUID, *, stripe_charge_id: str) -> None: charge = self._uow.fee_charges.get_by_id(fee_charge_id) diff --git a/backend/app/services/fees/fee_restatement_disclosure_service.py b/backend/app/services/fees/fee_restatement_disclosure_service.py index fe9bedc..be5851d 100644 --- a/backend/app/services/fees/fee_restatement_disclosure_service.py +++ b/backend/app/services/fees/fee_restatement_disclosure_service.py @@ -1,20 +1,5 @@ -"""`FeeRestatementDisclosureService` (S10 §6, FR-47) — implements -`app.services.restatement.restatement_service.FeeDisclosureChecker`, the optional hook -`RestatementService` calls after cross-checking an already-published period a restatement touched. - -Never reopens or adjusts an already-charged fee (out of v1 scope per ADR 10's own alternatives- -considered section) -- the only behavior here is recording a `fee_restatement_disclosure` row so -S8 can surface it to the customer as a documented limitation. - -**Takes a `Protocol`, not the concrete `FeesUnitOfWork`.** The real trigger sites -(`WashSaleService`, `CorporateActionService`) run under `LotsUnitOfWork`, not `FeesUnitOfWork` -- -and must, for the identical same-transaction reason `RestatementService`'s own module docstring -already gives (a fresh `UnitOfWork` would not see the correcting entry's own not-yet-committed -postings). `LotsUnitOfWork` composing `FeesModelsUnitOfWork` (`app/services/lots/uow.py`) is what -makes it satisfy this `Protocol` structurally, matching `SnapshotService`'s identical -`RestatementCapableUnitOfWork` pattern for a concrete-vs-`Protocol` parameter under -`mypy --strict`. -""" +"""Implements `FeeDisclosureChecker` (S10 §6, FR-47): records a disclosure row for an already-charged +period a restatement touched. Never reopens or adjusts the charge itself (out of v1 scope, ADR 10).""" from __future__ import annotations diff --git a/backend/app/services/fees/fee_summary_service.py b/backend/app/services/fees/fee_summary_service.py index 74c6bdc..ceab60a 100644 --- a/backend/app/services/fees/fee_summary_service.py +++ b/backend/app/services/fees/fee_summary_service.py @@ -1,8 +1,4 @@ -"""`FeeSummaryService` (S10 §7) — the single place that assembles a customer's fee/dunning read -model, so `GET /api/v1/fees` and `GET /api/v1/admin/customers//fees` (S8 §4 row 6) call the -same code path rather than two independently-implemented aggregations that could drift apart (the -same DRY/no-drift discipline S8 §6 edge case 4 states for balance, applied here to fees). -""" +"""Assembles a customer's fee/dunning read model, shared by the customer and admin fee endpoints (S10 §7).""" from __future__ import annotations diff --git a/backend/app/services/fees/high_water_mark_service.py b/backend/app/services/fees/high_water_mark_service.py index 9182c18..fc5dcb4 100644 --- a/backend/app/services/fees/high_water_mark_service.py +++ b/backend/app/services/fees/high_water_mark_service.py @@ -1,27 +1,7 @@ -"""`HighWaterMarkService` (S10 §3.2/§4, ADR 10, S10 §8 edge case 2) — tracks each customer's peak -in **TWR-adjusted** terms, never raw portfolio value directly. - -**The single most consequential correctness requirement in S10** (the spec's own words): a customer -depositing cash mechanically raises their portfolio value, and that must never be mistaken for -investment gain. The fix is to compare against a "shadow NAV" -- the dollar value the customer's -*first* funded balance would be worth today if it had only ever moved with investment performance, -never with a deposit or withdrawal -- rather than the live, flow-inflated portfolio balance. - -**Why this needs no new stored field beyond `high_water_mark.peak_value` (S10 §3.2's literal -schema).** `shadow_nav` reuses `TwrService.compute_twr` (S4, FR-17) end to end: `TwrService`'s own -per-sub-period return already excludes every flow by construction (`(end - begin - flow) / begin`), -so linking sub-period returns from a customer's very first funded day to today produces a cumulative -return figure that a deposit can never move. Multiplying that cumulative return onto the dollar -value of the customer's first funded day recovers a dollar-denominated "what would this be worth -today on performance alone" figure -- fully re-derivable from the ledger and `sub_period_return` on -every call, so `high_water_mark` only ever needs to persist the ratcheted peak itself, exactly as -S10 §3.2 describes it ("a cache, not a ledger... always re-derivable... if this row were ever -lost"). - -A pure deposit with zero market movement therefore contributes a `return_pct` of exactly zero for -the sub-period it lands in (proven by `TwrService._sub_period_return`'s own formula), so -`shadow_nav` does not move and `ratchet()` accrues nothing -- the property this sub-project's own -test suite (S10 §9) is built to prove with many randomized deposit/gain combinations. +"""Tracks each customer's peak in TWR-adjusted terms, never raw portfolio value (S10 §3.2/§4, ADR 10). + +Compares against a "shadow NAV" derived via `TwrService.compute_twr` so a deposit/withdrawal is +never mistaken for investment gain (S10 §8 edge case 2). """ from __future__ import annotations @@ -59,9 +39,7 @@ def __init__( self._now = now def shadow_nav(self, customer_id: uuid.UUID, as_of_date: date) -> Money | None: - """The TWR-adjusted dollar value driving the high-water-mark comparison (module - docstring). `None` when the customer has never funded an account yet -- there is no basis - to compound a return onto, and no fee can accrue before a first deposit exists.""" + """TWR-adjusted dollar value driving the HWM comparison. `None` if never funded.""" first_flow_date = self._first_flow_date(customer_id) if first_flow_date is None or first_flow_date > as_of_date: return None @@ -82,9 +60,7 @@ def shadow_nav(self, customer_id: uuid.UUID, as_of_date: date) -> Money | None: def get_or_create( self, customer_id: uuid.UUID, *, shadow_value: Money ) -> HighWaterMark: - """S10 §4: "creates at first-ever value if absent" -- a brand-new high-water-mark starts - pinned to today's shadow NAV, so the very first accrual day always yields zero gain - (nothing to be "above" yet).""" + """S10 §4: creates at first-ever value if absent, pinned to today's shadow NAV.""" existing = self._uow.high_water_marks.get_by_customer(customer_id) if existing is not None: return existing @@ -96,10 +72,7 @@ def get_or_create( return hwm def ratchet(self, hwm: HighWaterMark, *, shadow_value: Money) -> Money: - """S10 §4's `gain_above_hwm = max(0, current_value - hwm.peak_value)`, written in terms of - the TWR-adjusted `shadow_value` rather than raw portfolio value (S10 §8 edge case 2). The - peak only ratchets **up**, on the value that actually generated this gain -- never down, - and never on a value a deposit alone produced.""" + """S10 §4: `gain_above_hwm = max(0, shadow_value - hwm.peak_value)`; peak only ratchets up.""" gain = shadow_value - hwm.peak_value if gain <= Money("0.00"): return Money("0.00") diff --git a/backend/app/services/fees/payment_method_service.py b/backend/app/services/fees/payment_method_service.py index 924012f..0e29a6e 100644 --- a/backend/app/services/fees/payment_method_service.py +++ b/backend/app/services/fees/payment_method_service.py @@ -1,10 +1,4 @@ -"""`PaymentMethodService` (S10 §7) — attaches/updates the customer's Stripe-linked payment method. - -Stripe Elements tokenizes the card client-side; this service only ever receives the resulting -`payment_method_id` (`pm_...`) and hands it to `PaymentPort.attach_payment_method` -- Trueup never -handles raw card data (PCI scope stays with Stripe, root `CLAUDE.md`'s "buy don't build" posture for -anything payment-adjacent). -""" +"""Attaches/updates the customer's Stripe-linked payment method (S10 §7). Never handles raw card data.""" from __future__ import annotations diff --git a/backend/app/services/fees/uow.py b/backend/app/services/fees/uow.py index bf99c08..fe129cc 100644 --- a/backend/app/services/fees/uow.py +++ b/backend/app/services/fees/uow.py @@ -1,10 +1,4 @@ -"""`FeesUnitOfWork` — S10 spans S1's ledger, S4's TWR/valuation, S6's restatement machinery -(`SnapshotService.publish`/`PublishedSnapshotRepository` for the fee-charge watermark lock, and the -`RestatementCapableUnitOfWork` shape `RestatementService` needs for its own S10 hook), S2's identity -(the customer's email, for provisioning a Stripe customer), and its own `FeesModelsUnitOfWork`. -Composes rather than duplicates accessors, the same extension mechanism -`RebalanceUnitOfWork`/`RestatementUnitOfWork` already use for a cross-aggregate consumer. -""" +"""S10's UoW: composes `RestatementUnitOfWork`, `IdentityUnitOfWork`, `OpsUnitOfWork`, and `FeesModelsUnitOfWork`.""" from __future__ import annotations diff --git a/backend/app/services/identity/account_approval_service.py b/backend/app/services/identity/account_approval_service.py index a65294f..d366c8f 100644 --- a/backend/app/services/identity/account_approval_service.py +++ b/backend/app/services/identity/account_approval_service.py @@ -1,18 +1,5 @@ -"""`AccountApprovalService` (S2 §4, ADR 21) — the custodian-side account-approval lifecycle. - -Distinct from `KycService`: it only ever writes `customer.account_approval_status`, never -`customer.kyc_status` (S2 §3.1/§4's conjunction -- the two gates are independent, not aliases of -one another). **Decided (ADR 21): Alpaca Paper Trading has no per-customer onboarding verdict to -wait on**, so this transition is simulated -- approval fires automatically the moment -`kyc_status = approved`, with a `simulated: true` marker on the log entry so the distinction from a -genuine third-party verdict is never lost. - -Approval is also the natural moment this system first needs the customer's own ledger accounts to -exist: nothing before this point creates them (`register()`, Wave 2, only creates the `customer` -row), and `customer_cash_lock`'s own docstring says "every customer must have one" -- so -`approve_if_eligible` creates the `cash`/`customer_equity` accounts and the cash-lock row here, -idempotently, the same transaction as flipping the approval flag. -""" +"""Custodian-side account-approval lifecycle (S2 §4, ADR 21). Approval is simulated (Alpaca Paper +Trading has no per-customer verdict) and also provisions the customer's ledger accounts.""" from __future__ import annotations @@ -38,8 +25,7 @@ def __init__(self, uow: FundingUnitOfWork) -> None: self._uow = uow def approve_if_eligible(self, customer_id: uuid.UUID) -> bool: - """Idempotent: a no-op unless `kyc_status = approved` and approval has not already been - granted. Returns whether approval was granted by this call.""" + """Idempotent. Returns whether approval was granted by this call.""" customer = self._uow.customers.get_by_id(customer_id) if customer is None: raise ValueError(f"no customer found for id={customer_id!r}") diff --git a/backend/app/services/identity/auth.py b/backend/app/services/identity/auth.py index f8ad123..73e5da2 100644 --- a/backend/app/services/identity/auth.py +++ b/backend/app/services/identity/auth.py @@ -1,10 +1,4 @@ -"""Stateless authentication helpers (S0 §7.1/§7.2): password hashing, principal lookup, TOTP. - -Principal lookup goes through `IdentityUnitOfWork.customers`/`.staff` — the repositories -`app/models/identity/repository.py` already defines — rather than re-querying `Customer`/`Staff` -directly here, so there is exactly one place that knows how to read either table (DRY, -`backend/CLAUDE.md`). -""" +"""Stateless authentication helpers (S0 §7.1/§7.2): password hashing, principal lookup, TOTP.""" from __future__ import annotations @@ -23,11 +17,7 @@ _TOTP_ISSUER = "Trueup" -# A fixed, valid Argon2id hash of a password nobody can log in with. `authenticate()` verifies -# against this when no principal matches the given email, so an unknown-email login costs exactly -# the same Argon2 work as a wrong-password one — otherwise the *unknown-email* branch returns -# early with no hash to verify, and its faster response time becomes an account-enumeration -# oracle (OWASP A07 / API2). +# Dummy hash verified on unknown-email login to prevent timing-based account enumeration (OWASP A07). _DUMMY_HASH = ph.hash("trueup-timing-safety-dummy-password-never-a-real-account") @@ -51,12 +41,7 @@ def find_principal_by_email(uow: IdentityUnitOfWork, email: str) -> AuthPrincipa def find_principal_by_id(uow: IdentityUnitOfWork, user_id: uuid.UUID | str) -> AuthPrincipal | None: - """Callers that fetch and then mutate the result inside their own `UnitOfWork` block (e.g. - `mfa_enroll` fetching `staff` then setting `staff.totp_secret_encrypted`) depend on the - returned object staying tracked by `uow.session` so `uow.commit()` actually persists the - write -- do not detach it here. `load_user()` is the one caller that returns this object - *across* its own `UnitOfWork`'s exit; it detaches the object itself, at its own call site, - precisely because every other caller must not have that done on its behalf.""" + """Returns the object still tracked by `uow.session` — do not detach it here.""" parsed_id = user_id if isinstance(user_id, uuid.UUID) else uuid.UUID(user_id) customer = uow.customers.get_by_id(parsed_id) if customer is not None: @@ -65,13 +50,7 @@ def find_principal_by_id(uow: IdentityUnitOfWork, user_id: uuid.UUID | str) -> A def authenticate(uow: IdentityUnitOfWork, email: str, password: str) -> AuthPrincipal | None: - """Look up a principal by email and verify the password. - - Returns `None` for both "no such email" and "wrong password" — the auth controller must raise - the same error for both (S0 §7 login test list: a prober cannot distinguish the two), and this - is also where that indistinguishability is made true at the timing level, not just the - response-body level (see `_DUMMY_HASH`). - """ + """Returns `None` for both "no such email" and "wrong password" (indistinguishable, S0 §7).""" principal = find_principal_by_email(uow, email) if principal is None: verify_password(_DUMMY_HASH, password) diff --git a/backend/app/services/identity/bank_link_service.py b/backend/app/services/identity/bank_link_service.py index 8df8565..888c253 100644 --- a/backend/app/services/identity/bank_link_service.py +++ b/backend/app/services/identity/bank_link_service.py @@ -18,9 +18,7 @@ class BankLinkNotFoundError(RuntimeError): class BankPortNotConfiguredError(RuntimeError): - """Raised when `create_link` is called on a `BankLinkService` built without a `BankPort` -- - the webhook path (`apply_item_login_required` only) never needs one, so callers on that path - may omit it entirely.""" + """Raised when `create_link` is called on a `BankLinkService` built without a `BankPort`.""" class BankLinkService: @@ -29,8 +27,7 @@ def __init__(self, uow: IdentityUnitOfWork, *, bank_port: BankPort | None = None self._bank_port = bank_port def create_link(self, customer_id: uuid.UUID, *, plaid_public_token: str) -> BankLink: - """S2 §5.1: exchange the public token, then supersede any prior active/`requires_reauth` - link in the same transaction that activates the new one (FR-42).""" + """S2 §5.1: exchange the token; supersede any prior active link in the same transaction (FR-42).""" if self._bank_port is None: raise BankPortNotConfiguredError( "create_link requires a BankPort; this BankLinkService was built without one" @@ -46,9 +43,7 @@ def create_link(self, customer_id: uuid.UUID, *, plaid_public_token: str) -> Ban return new_link def apply_item_login_required(self, plaid_item_id: str) -> None: - """FR-43: a Plaid webhook reporting `ITEM_LOGIN_REQUIRED` transitions the named link to - `requires_reauth`. A stale webhook for an already-`superseded` link is ignored -- the - customer has already re-linked, so there is nothing left to flag.""" + """FR-43: `ITEM_LOGIN_REQUIRED` webhook transitions the link to `requires_reauth`.""" link = self._uow.bank_links.get_by_plaid_item_id(plaid_item_id) if link is None: raise BankLinkNotFoundError(f"no bank_link found for plaid_item_id={plaid_item_id!r}") diff --git a/backend/app/services/identity/deposit_service.py b/backend/app/services/identity/deposit_service.py index d7b9dba..4b08efb 100644 --- a/backend/app/services/identity/deposit_service.py +++ b/backend/app/services/identity/deposit_service.py @@ -26,17 +26,11 @@ from app.services.identity.funding_uow import FundingUnitOfWork _ACH_SETTLEMENT_CALENDAR_DAYS = 2 -"""A defensible engineering default standing in for Plaid's own ACH timeline (S2 §5.2 step 3) -- -flagged, like the deposit caps, for compliance review against actual NACHA network timing before -go-live (S2 §5.2's own framing).""" +"""Stand-in for Plaid's ACH timeline (S2 §5.2 step 3); flagged for compliance review before go-live.""" class FundingNotEligibleError(RuntimeError): - """S2 §3.1's conjunction: `kyc_status` and `account_approval_status` must both be `approved`. - - `reason` names the specific gate still pending/rejected so the customer-facing surface can show - *which* one, not a generic "not approved" message (S2 §7 edge case 2). - """ + """S2 §3.1: `kyc_status` and `account_approval_status` must both be `approved`.""" def __init__(self, reason: str) -> None: super().__init__(f"funding is not eligible: {reason}") @@ -48,8 +42,7 @@ class NoActiveBankLinkError(RuntimeError): class BankReauthRequiredError(RuntimeError): - """FR-43: the active link is `requires_reauth`. Never silently retried against the stale Item; - the customer must re-link (S2 §5.4).""" + """FR-43: the active link is `requires_reauth`; the customer must re-link (S2 §5.4).""" class DepositCapExceededError(RuntimeError): @@ -61,8 +54,7 @@ def __init__(self, cap: str) -> None: class SettlementObligationNotFoundError(RuntimeError): - """Raised when an ACH-return webhook names a `settlement_obligation` this system has none - for.""" + """Raised when an ACH-return webhook names an unknown `settlement_obligation`.""" @dataclass(frozen=True, slots=True) @@ -75,7 +67,7 @@ class DepositResult: def check_deposit_caps( amount: Money, *, deposited_today: Money, cap_per_transaction: Money, cap_per_day: Money ) -> None: - """S2 §5.2 step 2's two caps, as pure logic -- unit-testable with no database (S2 §8).""" + """S2 §5.2 step 2's two caps, as pure logic.""" if amount > cap_per_transaction: raise DepositCapExceededError("per_transaction") if deposited_today + amount > cap_per_day: @@ -85,8 +77,7 @@ def check_deposit_caps( def build_ach_return_correction_legs( *, cash_account_id: uuid.UUID, receivable_account_id: uuid.UUID, amount: Money ) -> list[PostingLeg]: - """S2 §5.2 step 4's correction entry, as pure construction -- unit-testable with no database - (S2 §8): moves `amount` from `cash` to `customer_receivable`, balanced to zero.""" + """S2 §5.2 step 4's correction entry: moves `amount` from `cash` to `customer_receivable`.""" return [ PostingLeg(account_id=cash_account_id, amount_money=-amount), PostingLeg(account_id=receivable_account_id, amount_money=amount), @@ -158,11 +149,7 @@ def initiate(self, customer_id: uuid.UUID, *, amount: Money) -> DepositResult: ) def apply_ach_return(self, settlement_obligation_id: uuid.UUID) -> None: - """FR-6: the ACH debit backing a deposit bounced. Fails the obligation (ADR 2's existing - `pending -> failed` branch) and, since a bounce always leaves a negative available-cash - position once the deposit's cash leg is accounted for, posts a `correction` entry moving - the amount from `cash` to `customer_receivable` -- a debt the customer now owes, never an - attempt to unwind whatever the cash was already used for (S2 §5.2 step 4).""" + """FR-6: ACH debit bounced. Fails the obligation and posts a correction entry (S2 §5.2 step 4).""" obligation = self._uow.settlement_obligations.get_by_id(settlement_obligation_id) if obligation is None: raise SettlementObligationNotFoundError( diff --git a/backend/app/services/identity/funding_uow.py b/backend/app/services/identity/funding_uow.py index 9d6dfd9..cadb6cd 100644 --- a/backend/app/services/identity/funding_uow.py +++ b/backend/app/services/identity/funding_uow.py @@ -1,28 +1,7 @@ -"""`FundingUnitOfWork` — one transaction boundary spanning identity (`customer`/`kyc_session`/ -`bank_link`), ledger (`account`/`journal_entry`/`posting`/`settlement_obligation`/ -`customer_cash_lock`), and ops (`inbound_event`/`idempotency_key`) repositories. - -S2's funding flows (`DepositService`/`WithdrawalService`/`AccountApprovalService`) need all three in -one `UnitOfWork`, per S0 §5's "exactly one commit point per operation": checking `kyc_status`/ -`account_approval_status`/`bank_link.status` (identity), posting a journal entry plus a settlement -obligation (ledger), and recording the `inbound_event` each traces back to (S1 §3.2's "every journal -entry traces back to exactly one inbound_event") must succeed or fail together, atomically. A -customer-initiated deposit/withdrawal has no incoming webhook to intake -- unlike a provider verdict --- so `DepositService`/`WithdrawalService` record their own `inbound_event` row directly (source -`plaid`, `signature_verified=True` since it is server-originated, not externally signed) rather than -going through `EventIntakeService`, which exists for signature-gated *inbound* provider calls only. - -Idempotency (S0 §8): `.idempotency_keys` is added here, not resolved via `app.core.idempotency`'s -process-wide `IdempotencyStore` resolver -- that resolver's lifecycle (when a fresh store is built -relative to the transaction it must share) is undecided and unused by any wave so far, whereas -composing `IdempotencyKeyRepository` directly onto this `UnitOfWork` gives the funding controllers -the same one-transaction guarantee (`find`, the deposit/withdrawal, and `save` all through -`self.session`, committed once) with no new lifecycle to invent. - -`IdentityUnitOfWork`, `LedgerUnitOfWork`, and `OpsUnitOfWork` are each plain `UnitOfWork` subclasses -adding their own `cached_property` repositories (S0 §5's documented extension mechanism); combining -them via ordinary multiple inheritance -- rather than duplicating any of them -- is that same -mechanism composed, not a new one. +"""One transaction boundary spanning identity, ledger, and ops repositories for S2's funding flows. + +Composes `IdentityUnitOfWork`, `LedgerUnitOfWork`, and `OpsUnitOfWork` via multiple inheritance +(S0 §5), and adds idempotency-key/order/approval-hold repos for the same commit. """ from __future__ import annotations @@ -44,12 +23,7 @@ def idempotency_keys(self) -> IdempotencyKeyRepository: @cached_property def orders(self) -> OrderRepository: - """S3's `order`/`approval_hold` repos, added here (not a base-class change) so - `OrderHoldsProvider` (`app/services/orders/holds_provider.py` -- "the real - `CashPolicyService.HoldsProvider`... replaces `NullHoldsProvider` at its wiring point, - `app/controllers/api/funding.py`") can finally be wired where its own docstring already - says it belongs, without a new `UnitOfWork` class -- both repositories take any - `UnitOfWork`, no `OrdersUnitOfWork`-specific mixin required.""" + """S3's order repo, added here so `OrderHoldsProvider` can be wired in without a new UoW class.""" return OrderRepository(self) @cached_property diff --git a/backend/app/services/identity/kyc_service.py b/backend/app/services/identity/kyc_service.py index 0c6cc0f..7a9014f 100644 --- a/backend/app/services/identity/kyc_service.py +++ b/backend/app/services/identity/kyc_service.py @@ -1,16 +1,4 @@ -"""`KycService` (S2 §4, ADR 9) — starts Stripe Identity verification sessions and applies the -provider's verdict once it arrives. - -The verdict itself never arrives synchronously (`KycPort.create_verification_session` only starts -a session); `apply_verification_verdict` is what a webhook-triggered caller invokes once Stripe's -own event names the session and its new status (S2 §6). - -`map_verification_session_status` -- ADR 9's status-mapping table -- lives here, in the service -layer, not in `app/integrations/stripe/`: `.importlinter`'s `services-use-ports-only` contract -forbids `app.services` from importing a concrete adapter module at all (S0 §3, DIP), and the -mapping is domain policy (which Stripe session statuses count as our `approved`/`rejected`/ -`pending`), not a provider call -- it belongs on this side of the port regardless. -""" +"""Starts Stripe Identity verification sessions and applies the provider's verdict (S2 §4, ADR 9).""" from __future__ import annotations @@ -35,10 +23,7 @@ class CustomerNotFoundError(RuntimeError): def map_verification_session_status( stripe_status: str, *, attempt_number: int, max_attempts: int ) -> KycSessionStatus: - """ADR 9's status mapping: `requires_input`/`processing` -> `pending`, `verified` -> - `approved`, `canceled` -> `rejected`, and `requires_input` past `KYC_MAX_ATTEMPTS` -> - `rejected` (never a naive "not yet verified = rejected" simplification -- a `processing` - session stuck indefinitely still reports `pending`, per ADR 9's explicit warning).""" + """ADR 9's status mapping: verified→approved, canceled→rejected, else pending (rejected past cap).""" if stripe_status == "verified": return KycSessionStatus.APPROVED if stripe_status == "canceled": @@ -51,18 +36,12 @@ def map_verification_session_status( class KycPortNotConfiguredError(RuntimeError): - """Raised when `start_verification` is called on a `KycService` built without a `KycPort` -- - the webhook path (`apply_verification_verdict` only) never needs one (S2 §4: the verdict never - arrives through this port), so callers on that path may omit it entirely.""" + """Raised when `start_verification` is called on a `KycService` built without a `KycPort`.""" class KycLockedError(RuntimeError): - """`start_verification` is blocked: the customer's `kyc_status` locked to `rejected` after - exhausting `KYC_MAX_ATTEMPTS` (S2 §3.2/§9), and only an adviser's `POST - /admin/kyc-overrides/` (S8 §4 row 5) can reopen it. Deliberately narrower than - "kyc_status is rejected" alone -- a single canceled attempt (well below the cap) also sets - `kyc_status = rejected`, but S8 §6 edge case 3 only locks out resubmission once attempts are - actually exhausted, not on the customer's first cancellation.""" + """`kyc_status` locked to `rejected` after exhausting `KYC_MAX_ATTEMPTS` (S2 §3.2/§9); + only an admin override (S8 §4 row 5) can reopen it.""" class KycService: @@ -80,10 +59,7 @@ def __init__( self._now = now def start_verification(self, customer_id: uuid.UUID) -> KycSessionHandle: - """S2 §5.1/§6: `POST /identity/kyc-sessions`. Locked-`rejected` (S2 §9's own reopening - gate, now implemented by S8 §4 row 5's admin override) blocks a fresh attempt outright, - before the provider is ever called -- otherwise always opens a fresh attempt, advancing - `attempt_number` so the override action has something to reopen.""" + """S2 §5.1/§6: `POST /identity/kyc-sessions`. Blocked outright if locked-`rejected`.""" customer = self._uow.customers.get_by_id(customer_id) if customer is None: raise CustomerNotFoundError(f"no customer found for id={customer_id!r}") @@ -116,20 +92,30 @@ def start_verification(self, customer_id: uuid.UUID) -> KycSessionHandle: self._uow.kyc_sessions.add(session_row) return handle + def sync_latest_verification(self, customer_id: uuid.UUID) -> uuid.UUID | None: + """Safety net for a verdict webhook that hasn't arrived (or, in local dev, can't reach the + app at all): polls the provider directly for the customer's latest session and feeds the + result through the exact same mapping/resolve path a webhook would. No-ops if there is no + session yet or the latest one is already terminal, so this never calls out to the provider + needlessly.""" + latest = self._uow.kyc_sessions.latest_for_customer(customer_id) + if latest is None or latest.status is not KycSessionStatus.PENDING: + return None + if self._kyc_port is None: + raise KycPortNotConfiguredError( + "sync_latest_verification requires a KycPort; this KycService was built without one" + ) + stripe_status = self._kyc_port.retrieve_verification_session( + provider_session_id=latest.provider_session_id + ) + return self.apply_verification_verdict( + provider_session_id=latest.provider_session_id, stripe_status=stripe_status + ) + def apply_verification_verdict( self, *, provider_session_id: str, stripe_status: str ) -> uuid.UUID | None: - """S2 §4's state machine, applied to the `kyc_session` row Stripe's own webhook names. - - A session Stripe reports as still `pending` (`requires_input`/`processing`, below the - attempt cap) resolves to nothing here -- `KycSession.status` stays `pending` and no - `resolve()` call happens, since `resolve()`'s single-transition guard (S2 §3.2) only - permits a `pending -> terminal` move, never a no-op re-write of `pending` onto itself. - - Returns the affected `customer_id` once a terminal verdict is applied, `None` when the - verdict is still `pending` -- the caller (the webhook controller) uses this to decide - whether to also invoke `AccountApprovalService` for this customer. - """ + """S2 §4's state machine. Returns `customer_id` on a terminal verdict, `None` if still pending.""" session_row = self._uow.kyc_sessions.get_by_provider_session_id(provider_session_id) if session_row is None: raise CustomerNotFoundError( diff --git a/backend/app/services/identity/null_holds_provider.py b/backend/app/services/identity/null_holds_provider.py index 4b71ac4..b9767a2 100644 --- a/backend/app/services/identity/null_holds_provider.py +++ b/backend/app/services/identity/null_holds_provider.py @@ -1,12 +1,4 @@ -"""`NullHoldsProvider` — a stand-in `HoldsProvider` (S1 §5) until S3 wires the real one. - -`CashPolicyService`'s own module docstring is explicit that there is no default `HoldsProvider`, -since a silent "always zero" implementation would produce a wrong `investable`/`withdrawable` -figure forever if a caller forgot to wire the real one. This class is the opposite of silent: it is -named, documented, and injected explicitly at the funding controllers' wiring point -- the one -place that needs to change, with no change to `WithdrawalService`/`DepositService` themselves, once -S3's `ApprovalHoldService` exists and a real `HoldsProvider` replaces this one. -""" +"""Stand-in `HoldsProvider` (S1 §5) until S3's real one is wired in.""" from __future__ import annotations @@ -19,9 +11,7 @@ class NullHoldsProvider: - """Implements `HoldsProvider` (structural) with zero holds and zero open buy commitments -- - correct only because S3's order-approval-hold and open-buy-commitment mechanisms do not exist - yet. Replace at the wiring point in `app/controllers/api/funding.py`, not here.""" + """Implements `HoldsProvider` with zero holds and zero open buy commitments.""" def holds(self, customer_id: uuid.UUID) -> Money: return Money("0.00") diff --git a/backend/app/services/identity/uow.py b/backend/app/services/identity/uow.py index e647af1..154a6aa 100644 --- a/backend/app/services/identity/uow.py +++ b/backend/app/services/identity/uow.py @@ -16,6 +16,7 @@ SqlStaffRepository, StaffRepository, ) +from app.models.identity.staff_api_token import StaffApiTokenRepository class IdentityUnitOfWork(UnitOfWork): @@ -34,3 +35,7 @@ def kyc_sessions(self) -> KycSessionRepository: @cached_property def bank_links(self) -> BankLinkRepository: return SqlBankLinkRepository(self) + + @cached_property + def staff_api_tokens(self) -> StaffApiTokenRepository: + return StaffApiTokenRepository(self) diff --git a/backend/app/services/identity/withdrawal_service.py b/backend/app/services/identity/withdrawal_service.py index 43e6dbd..54674a0 100644 --- a/backend/app/services/identity/withdrawal_service.py +++ b/backend/app/services/identity/withdrawal_service.py @@ -25,8 +25,7 @@ class FundingNotEligibleError(RuntimeError): - """S2 §3.1's conjunction, checked on every withdrawal too -- not just deposits (per S2 §3.1: - both services check both statuses every time, not once at account creation).""" + """S2 §3.1's conjunction, checked on every withdrawal too, not just deposits.""" def __init__(self, reason: str) -> None: super().__init__(f"funding is not eligible: {reason}") @@ -38,14 +37,11 @@ class NoActiveBankLinkError(RuntimeError): class BankReauthRequiredError(RuntimeError): - """FR-43: the active link is `requires_reauth`. Never silently retried against the stale - Item.""" + """FR-43: the active link is `requires_reauth`.""" class InsufficientWithdrawableCashError(RuntimeError): - """S2 §5.3/ADR 5: `amount` exceeds `withdrawable` -- checked even when it is within - `investable` (S2 §7 edge case 4). Never relaxed to `investable`; ADR 5 calls swapping the two - "a regulatory-grade bug, not a cosmetic one".""" + """S2 §5.3/ADR 5: `amount` exceeds `withdrawable`, even when within `investable`.""" @dataclass(frozen=True, slots=True) diff --git a/backend/app/services/intake/dispatch.py b/backend/app/services/intake/dispatch.py index 902053a..1f3bff8 100644 --- a/backend/app/services/intake/dispatch.py +++ b/backend/app/services/intake/dispatch.py @@ -1,24 +1,7 @@ -"""`InboundEventDispatcher` — the composition point every source's inbound event flows through -after `EventIntakeService` hands it to the outbox (S0 §6). - -`OutboxWorker` (`app/workers/outbox.py`, Wave 2) requires a concrete `OutboxTaskHandler`, but -nothing implemented one: S0 §6 says every source (KYC verdicts, Plaid events, Alpaca fills, and -whatever S5-S12 adds later) shares this exact hand-off, so the thing that reads an `inbound_event` -row's `.source` and routes to the right per-source service is inherently cross-track — it cannot -be owned by any single S-spec's file list without that spec silently taking ownership of every -other source too. Built here, once, as infrastructure (the same reasoning as `ports.py`), -independent of which per-source handlers exist yet. - -**How a track registers a handler**: call `dispatcher.register(InboundEventSource.STRIPE, -your_handler)` wherever your service wiring happens. A handler receives the raw, still-JSON -`payload` dict exactly as `inbound_event.payload` stored it — parsing it into a typed model is the -handler's own job, the same way `EventIntakeService.intake()` already expects a caller-parsed -`IncomingEvent` on the way in. - -**Not yet wired end-to-end**: no track's handlers are registered here, and no process constructs -an `OutboxWorker` with this dispatcher and actually runs it (Wave 2 built `OutboxWorker` itself, -fully tested standalone, but never stood it up as a live process either). Tracked as owed -operational work, not a Wave 4 blocker -- each track's own tests exercise `handle()` directly. +"""Routes an `inbound_event` row to its source's registered handler after the outbox hands it off (S0 §6). + +Not yet wired end-to-end: no track's handlers are registered here, and no process runs +an `OutboxWorker` with this dispatcher yet. """ from __future__ import annotations @@ -32,15 +15,13 @@ class InboundEventFetcher(Protocol): - """What the dispatcher needs from a UnitOfWork to resolve an event by id — narrower than - `OpsUnitOfWork` itself, so a test can supply a minimal fake.""" + """What the dispatcher needs from a UnitOfWork to resolve an event by id.""" def get_by_id(self, event_id: uuid.UUID) -> Any: ... # returns InboundEvent | None class UnregisteredSourceError(RuntimeError): - """Raised rather than silently dropping an event whose source has no registered handler -- - a source with no handler is a wiring gap, not a no-op.""" + """Raised rather than silently dropping an event whose source has no registered handler.""" class InboundEventDispatcher: @@ -50,17 +31,11 @@ def __init__(self) -> None: def register( self, source: InboundEventSource, handler: Any ) -> None: - """`handler` is any callable of shape `(payload: dict[str, Any]) -> None`. Registering the - same source twice replaces the previous handler rather than erroring -- re-registration - happens naturally across test setup/teardown and hot-reload in development.""" + """`handler` is any callable of shape `(payload: dict[str, Any]) -> None`. Re-registering replaces.""" self._handlers[source] = handler def handle(self, *, task: str, payload: dict[str, Any], uow: InboundEventFetcher) -> None: - """Matches `OutboxTaskHandler`'s shape (`app/workers/outbox.py`) plus one extra keyword - (`uow`) needed to resolve the event row -- a caller wires this in via a small closure/ - partial when constructing the `OutboxWorker`, since `OutboxTaskHandler.handle` itself - takes only `(task, payload)`. - """ + """Matches `OutboxTaskHandler`'s shape plus one extra keyword (`uow`) to resolve the event row.""" if task != "process_inbound_event": raise UnregisteredSourceError(f"no dispatcher route for outbox task {task!r}") diff --git a/backend/app/services/intake/event_intake.py b/backend/app/services/intake/event_intake.py index 278c2cf..054aea1 100644 --- a/backend/app/services/intake/event_intake.py +++ b/backend/app/services/intake/event_intake.py @@ -31,11 +31,7 @@ def enqueue(self, task: str, payload: dict[str, str]) -> object: ... class IntakeUnitOfWork(Protocol): - """Shaped exactly like `app.jobs.base.JobUnitOfWork` (the same `UnitOfWork`-satisfying - Protocol pattern, proven against a real `cached_property`-based repository and the real - 3-argument context-manager `__exit__`) so any concrete `UnitOfWork` subclass exposing - `.inbound_events`/`.outbox` -- however it composes them -- satisfies this Protocol structurally, - with no adapter class required.""" + """Structural: any `UnitOfWork` exposing `.inbound_events`/`.outbox` satisfies this.""" @property def inbound_events(self) -> InboundEventWriter: ... diff --git a/backend/app/services/ledger/cash_policy_service.py b/backend/app/services/ledger/cash_policy_service.py index 412b435..b889b34 100644 --- a/backend/app/services/ledger/cash_policy_service.py +++ b/backend/app/services/ledger/cash_policy_service.py @@ -1,13 +1,4 @@ -"""`CashPolicyService` (S1 §5, ADR 5) — the two pure policy functions everything else in the -system reads instead of a stored "balance." - -`holds(customer)`/`open_buy_commitments(customer)` are **owned by S3** (§5): this module defines -the contract as a `Protocol` and composes it, without implementing the holds table itself. Until -S3 wires a real implementation, callers supply whatever `HoldsProvider` they have -- there is no -default here, since a silent "always zero" implementation would produce a wrong `investable`/ -`withdrawable` figure forever if a caller forgot to wire the real one (the same reasoning behind -`Watermark`'s required, no-default `as_of`). -""" +"""Pure cash policy functions everything else reads instead of a stored balance (S1 §5, ADR 5).""" from __future__ import annotations @@ -40,19 +31,7 @@ def __init__(self, uow: LedgerUnitOfWork, *, holds_provider: HoldsProvider) -> N self._holds_provider = holds_provider def settled_cash(self, customer_id: uuid.UUID) -> Money: - """Cash postings whose journal entry needs no settlement confirmation, whose obligation - has confirmed, or that are a **pending outflow** (§5). - - The third clause fixes a real double-spend window (S0 §10.1 audit finding F2): a - `trade_buy` fill posts its `-cost` cash leg immediately but carries a `pending` - settlement obligation until T+1 confirms. Without this clause that negative posting was - excluded from the sum entirely -- not merely deferred -- so `settled_cash` (and therefore - `investable`) stayed exactly as if the buy had never happened for the whole T+1 window, - even though the cash is already spent. An unsettled *inflow* (a pending deposit/sell) must - still wait for confirmation before counting as settled (ADR 5's asymmetry is about - inflows, never outflows) -- a customer's own outflow commitment is real the instant they - make it, regardless of whether the counterparty has settled its side yet. - """ + """Cash postings needing no settlement, already confirmed, or a pending outflow (§5).""" no_obligation_needed = ~select(SettlementObligation.id).where( SettlementObligation.journal_entry_id == Posting.journal_entry_id ).exists() @@ -79,9 +58,7 @@ def unsettled_sale_proceeds(self, customer_id: uuid.UUID) -> Money: ) def unsettled_deposit_proceeds(self, customer_id: uuid.UUID) -> Money: - """Added alongside `unsettled_sale_proceeds` per S1 §5's amendment: a deposit is - investable immediately, before its own obligation confirms, exactly as any other - unsettled inflow.""" + """A deposit is investable immediately, before its own obligation confirms (S1 §5).""" return self._unsettled_obligation_total(customer_id, entry_type=JournalEntryType.DEPOSIT) def _unsettled_obligation_total( @@ -101,8 +78,7 @@ def _unsettled_obligation_total( @staticmethod def _as_money(value: Money | None) -> Money: - """`COALESCE(..., 0)` guarantees SQL never returns `NULL`; mypy still sees the column's - static type as nullable, so this narrows it in one place rather than at every call site.""" + """Narrows the nullable column type; SQL's `COALESCE` guarantees a non-null value.""" return value if value is not None else Money("0.00") def withdrawable(self, customer_id: uuid.UUID) -> Money: @@ -110,8 +86,7 @@ def withdrawable(self, customer_id: uuid.UUID) -> Money: return self.settled_cash(customer_id) - self._holds_provider.holds(customer_id) def investable(self, customer_id: uuid.UUID) -> Money: - """Additionally counts unsettled inflows, deliberately **not** given to `withdrawable` - (ADR 5's asymmetry, by design).""" + """Counts unsettled inflows too; deliberately not given to `withdrawable` (ADR 5).""" return ( self.settled_cash(customer_id) + self.unsettled_sale_proceeds(customer_id) diff --git a/backend/app/services/ledger/posting_service.py b/backend/app/services/ledger/posting_service.py index 491992f..6ce0364 100644 --- a/backend/app/services/ledger/posting_service.py +++ b/backend/app/services/ledger/posting_service.py @@ -1,10 +1,6 @@ -"""`PostingService` (S1 §3.2-§3.4) — the one path every journal entry is written through. +"""The one path every journal entry is written through (S1 §3.2-§3.4). -Validates the same two invariants the database enforces (§3.3's dimension rule, §3.4/ADR 17's -zero-sum rule) *before* insert, so a bad entry fails with a clear application-level error in the -common case; the DB trigger (`app/models/ledger/posting.py`) is the backstop that catches it -regardless, exactly the "repository's job is writing correct postings; the trigger is the backstop -if it doesn't" split S0 §5 describes. +Validates the dimension and zero-sum invariants before insert; the DB trigger is the backstop. """ from __future__ import annotations @@ -26,8 +22,7 @@ @dataclass(frozen=True, slots=True) class PostingLeg: - """One leg of a journal entry: exactly one of `amount_money`/`quantity_units` is set, - matching §3.3's `CHECK`.""" + """One leg of a journal entry: exactly one of `amount_money`/`quantity_units` is set (§3.3).""" account_id: uuid.UUID amount_money: Money | None = None @@ -39,8 +34,7 @@ class UnbalancedEntryError(ValueError): class InvalidPostingLegError(ValueError): - """A leg sets zero or both of `amount_money`/`quantity_units` (§3.3's `CHECK`, checked here - ahead of the database).""" + """A leg sets zero or both of `amount_money`/`quantity_units` (§3.3).""" class PostingService: @@ -76,11 +70,7 @@ def correct( reason: str, memo: str | None = None, ) -> JournalEntry: - """Supersede `original` with a new entry of the same `entry_type` (S1 §3.2's - disambiguation: a corrected `trade_buy` stays `entry_type = trade_buy`). The new entry - carries `superseded_by = original.id` -- `original` itself is never written to; see - `app/models/ledger/journal_entry.py`'s module docstring for why the link runs this - direction.""" + """Supersede `original` with a new entry of the same `entry_type` (S1 §3.2).""" return self._write( entry_type=original.entry_type, effective_date=effective_date, diff --git a/backend/app/services/lots/_shared.py b/backend/app/services/lots/_shared.py index 8e4f616..0c334d8 100644 --- a/backend/app/services/lots/_shared.py +++ b/backend/app/services/lots/_shared.py @@ -1,18 +1,4 @@ -"""Account-bootstrap and event-synthesis helpers shared by S5's three services. - -`get_or_create_customer_account`/`get_or_create_house_account` follow -`DepositService._account_for`'s exact precedent (S2): lazily create a ledger account the first -time a customer (or the house) needs one, rather than requiring some earlier step to have done it. -`DIVIDEND_INCOME` is created house-wide (`customer_id=None`) per `account.py`'s own module -docstring ("null only for house accounts (`fees_expense`, `dividend_income`)") -- an already- -decided S1 convention this module conforms to, not one it introduces. - -`record_inbound_event` follows `DepositService._record_inbound_event`'s exact precedent: every -`journal_entry.source_event_id` must reference a real `inbound_event` row, and -`InboundEventDispatcher.handle()` only forwards a handler the raw payload, not the id of the -`inbound_event` that triggered it (`app/services/intake/dispatch.py`) -- so each posting synthesizes -its own audit-trail row here, exactly as S2 already does for deposits/withdrawals. -""" +"""Account-bootstrap and event-synthesis helpers shared by S5's three services.""" from __future__ import annotations @@ -49,9 +35,7 @@ def get_or_create_customer_account( def require_customer_account( uow: LotsUnitOfWork, *, customer_id: uuid.UUID, role: AccountRole ) -> Account: - """For roles an earlier step is already responsible for creating (`cash`, matching - `DepositService._account_for`'s strict branch) -- a missing row here is a real invariant - violation (account approval should have created it), never a lazy-bootstrap opportunity.""" + """For roles an earlier step already creates (`cash`); a missing row is an invariant violation.""" account = uow.session.execute( select(Account).where(Account.customer_id == customer_id, Account.role == role) ).scalar_one_or_none() diff --git a/backend/app/services/lots/corporate_action_service.py b/backend/app/services/lots/corporate_action_service.py index 66a1080..8db775a 100644 --- a/backend/app/services/lots/corporate_action_service.py +++ b/backend/app/services/lots/corporate_action_service.py @@ -1,17 +1,4 @@ -"""`CorporateActionService` (S5 §6) — the dividend two-step and the units-only split entry. - -Holdings are read from `tax_lot` state directly, never a parallel holdings tally (S5 §1's own -framing, "derive realized/unrealized gains from lot state alone") -- so `declare_dividend_ex_date` -and `apply_split` both start from `TaxLotRepository.list_customers_holding`, applying the action to -every customer currently holding the security rather than requiring a caller to already know who -they are. - -**No caller exists yet for any of this class's three methods (S5's own open item, -DECISION-LOG.md).** Each still calls `RestatementService.restate()` after every entry it posts -(S6 §4: `dividend`/`split` are two of S6's named trigger `entry_type`s), so restatement fires -correctly the moment a real caller (a pay-date job, an operator action) lands -- not something to -wire only once that caller exists. -""" +"""The dividend two-step and the units-only split entry (S5 §6). Holdings read from `tax_lot` state directly.""" from __future__ import annotations @@ -50,9 +37,7 @@ def __init__(self, uow: LotsUnitOfWork) -> None: def declare_dividend_ex_date( self, *, security_id: uuid.UUID, per_share_amount: Price, ex_date: date ) -> list[JournalEntry]: - """S5 §6.1's ex-date step: entitlement recognized, cash not yet moved. One entry per - customer currently holding `security_id` (`dividend_income` is a single house account - per `account.py`'s own convention; `dividend_receivable` is per-customer).""" + """S5 §6.1 ex-date step: entitlement recognized, cash not yet moved. One entry per holder.""" entries: list[JournalEntry] = [] income_account = get_or_create_house_account(self._uow, role=AccountRole.DIVIDEND_INCOME) @@ -101,10 +86,7 @@ def declare_dividend_ex_date( def pay_dividend( self, *, customer_id: uuid.UUID, amount: Money, pay_date: date ) -> JournalEntry: - """S5 §6.1's pay-date step: cash finally arrives, days later. `amount` is the same figure - `declare_dividend_ex_date` posted to that customer's receivable -- the caller (a future - pay-date job, S5 §9's open parameter on how corporate actions are triggered) is - responsible for reading it back off that entry/receivable balance.""" + """S5 §6.1 pay-date step: cash finally arrives, days later.""" cash_account = require_customer_account( self._uow, customer_id=customer_id, role=AccountRole.CASH ) @@ -156,9 +138,7 @@ def pay_dividend( def apply_split( self, *, security_id: uuid.UUID, ratio: int | Decimal, effective_date: date ) -> list[JournalEntry]: - """S5 §6.2: doubles (or `ratio`-multiplies) every open lot's quantity for `security_id`, - posts a units-only entry per affected customer (S1 §3.4's worked example -- no money legs - at all, since value and return must not move, FR-24).""" + """S5 §6.2: multiplies every open lot's quantity by `ratio`, posts a units-only entry.""" if ratio <= 1: raise ValueError(f"split ratio must be greater than 1, got {ratio!r}") diff --git a/backend/app/services/lots/lot_consumption_service.py b/backend/app/services/lots/lot_consumption_service.py index 1d832ba..692fc07 100644 --- a/backend/app/services/lots/lot_consumption_service.py +++ b/backend/app/services/lots/lot_consumption_service.py @@ -1,12 +1,5 @@ -"""`LotConsumptionService` (S5 §4) — opens a tax lot on every buy fill, consumes lots (FIFO -default, specific-ID override, ADR 4) on every sell fill, and posts the `trade_buy`/`trade_sell` -ledger entries those events require (S1 §3.4's worked example; "Sells... are S5's to define, -since they require lot cost basis S1 does not compute"). - -Called from `AlpacaTradeUpdateHandler._record_lot_fill` (`app/services/orders/ -trade_update_handler.py`) on every `fill`/`partial_fill` event -- the natural integration point -(S3's fill-confirmation path). -""" +"""Opens a tax lot per buy fill, consumes lots (FIFO/specific-ID, ADR 4) per sell fill, and posts +the `trade_buy`/`trade_sell` ledger entries (S5 §4).""" from __future__ import annotations @@ -37,19 +30,15 @@ from app.services.lots.uow import LotsUnitOfWork _SETTLEMENT_TRADING_DAYS = 1 -"""T+1, per the brief's own framing ("trades settle T+1").""" +"""Trades settle T+1.""" class InsufficientLotsError(RuntimeError): - """A sell fill's quantity exceeds every open lot's remaining quantity for that security (S5 - §7 edge case 6) -- raised rather than silently creating a negative-quantity lot; this is a - reconciliation-worthy anomaly (S3's holdings tracking disagreeing with S5's lot state), not a - data error to absorb quietly.""" + """A sell fill's quantity exceeds every open lot's remaining quantity (S5 §7 edge case 6).""" class UnknownTaxLotError(RuntimeError): - """A specific-ID designation names a lot that does not exist, or belongs to a different - customer/security than the sell fill itself.""" + """A specific-ID designation names a lot that doesn't exist or belongs to another customer/security.""" class LotConsumptionService: @@ -75,8 +64,7 @@ def record_buy_fill( price: Price, filled_at: datetime, ) -> TaxLot: - """Opens a tax lot and posts the `trade_buy` entry (position_units/position_cost/cash, - S1 §3.4's worked example minus the fee leg S3's fill payload carries no data for).""" + """Opens a tax lot and posts the `trade_buy` entry (position_units/position_cost/cash).""" fill_date = self._market_clock.market_date(filled_at) cost = price * quantity @@ -137,7 +125,7 @@ def record_buy_fill( ) window_closes_at = self._market_clock.session_close(settlement_date) - if window_closes_at is None: # pragma: no cover - defensive: T+1 of a trading day is one + if window_closes_at is None: # pragma: no cover - defensive raise RuntimeError( f"expected_settlement_date {settlement_date} is not a trading day per the " "injected calendar -- MarketClock.add_trading_days should never produce this" @@ -173,15 +161,7 @@ def record_sell_fill( designated_lot_ids: Sequence[uuid.UUID] | None = None, ) -> list[LotConsumption]: """Consumes lots (FIFO default, specific-ID override -- ADR 4, S5 §4) and posts the - `trade_sell` entry with realized gain/loss legs (S1 §3.4: "sells... require lot cost - basis S1 does not compute"). - - `designated_lot_ids` has no caller yet: nothing in this codebase's `Order`/controller - layer collects a customer's specific-lot election (ADR 4's own designation-event/ - `superseded_by` versioning is a separate, not-yet-specified mechanism). Accepted here so - the FIFO-vs-override branch matches S5 §4's algorithm shape; a future order-entry - enhancement can populate it without this method's shape changing. - """ + `trade_sell` entry with realized gain/loss legs.""" fill_date = self._market_clock.market_date(filled_at) lots = self._select_lots_to_consume(customer_id, security_id, designated_lot_ids) diff --git a/backend/app/services/lots/uow.py b/backend/app/services/lots/uow.py index eab6678..4fb4615 100644 --- a/backend/app/services/lots/uow.py +++ b/backend/app/services/lots/uow.py @@ -1,22 +1,5 @@ -"""`LotsUnitOfWork` — S5 needs `LedgerUnitOfWork` (accounts, postings, `tax_lots`/ -`lot_consumptions`/`wash_sale_adjustments`) and `OpsUnitOfWork` (`inbound_events`, for the -synthesized-event-per-posting pattern `DepositService`/`WithdrawalService` already establish). -Composes both rather than duplicating their repository accessors (S0 §5's extension mechanism), -the identical shape `ValuationUnitOfWork` (S4) already uses for the same kind of cross-aggregate -consumer. - -`MarketDataUnitOfWork` and `RestatementModelsUnitOfWork` (S6) are composed here too: -`WashSaleService` and `CorporateActionService` call `RestatementService.restate()` inline, in the -same transaction as the correcting entry they just posted (`app.models.restatement`'s own module -docstring explains why that must be the *same* `UnitOfWork`, not a fresh one). `OrdersUnitOfWork` -gets both transitively, being a `LotsUnitOfWork` itself -- no other file needs to change for the -real, already-wired wash-sale trigger site to work. - -`FeesModelsUnitOfWork` (S10) is composed here too, additively: S10's `RestatementService` hook -(`fee_disclosure_checker`) needs `.fee_charges`/`.fee_restatement_disclosures` on the *same* -`UnitOfWork` `WashSaleService`/`CorporateActionService` already hold, for the identical -same-transaction reason as the two mixins above -- not a second `UnitOfWork` instance, and not a -`Protocol` widened to force every other structural implementer to grow these accessors too.""" +"""S5 UoW: composes ledger, ops, market data, restatement, and fees mixins for the same-transaction +requirements of `WashSaleService`/`CorporateActionService`.""" from __future__ import annotations diff --git a/backend/app/services/lots/wash_sale_service.py b/backend/app/services/lots/wash_sale_service.py index fccb904..103881f 100644 --- a/backend/app/services/lots/wash_sale_service.py +++ b/backend/app/services/lots/wash_sale_service.py @@ -1,10 +1,6 @@ -"""`WashSaleService` (S5 §5, ADR 11) — the reactive same-CUSIP wash-sale check. +"""The reactive same-CUSIP wash-sale check (S5 §5, ADR 11). -Two symmetric entry points, matching ADR 11's "composes cleanly... no new temporal reasoning -required": `on_loss_sale` handles a buy that already happened before the sale (checked immediately), -`on_buy_fill` handles a buy arriving after an earlier loss sale (checked reactively when the buy -posts). Both funnel into `_apply_adjustment`, so the disallowance math and posting shape live in -exactly one place. +Two symmetric entry points, `on_loss_sale` and `on_buy_fill`, both funnel into `_apply_adjustment`. """ from __future__ import annotations @@ -46,8 +42,7 @@ def on_loss_sale( customer_id: uuid.UUID, security_id: uuid.UUID, ) -> None: - """The trailing-window side: a same-CUSIP buy that already happened before this loss - sale. Called once per loss-realizing `lot_consumption` a sell fill produces.""" + """Trailing-window side: a same-CUSIP buy that already happened before this loss sale.""" if consumption.realized_gain_loss >= Money("0.00"): return if self._uow.wash_sale_adjustments.exists_for_consumption(consumption.id): @@ -66,8 +61,7 @@ def on_loss_sale( self._apply_adjustment(consumption, replacement_lot) def on_buy_fill(self, new_lot: TaxLot) -> None: - """The forward-window side: a same-CUSIP buy landing after an earlier loss sale. Called - once per buy fill, scanning that security's still-unadjusted loss consumptions.""" + """Forward-window side: a same-CUSIP buy landing after an earlier loss sale.""" window_start, window_end = self._window(new_lot.acquired_at) candidates = self._uow.lot_consumptions.find_unadjusted_losses_in_window( new_lot.customer_id, @@ -137,8 +131,7 @@ def _apply_adjustment(self, consumption: LotConsumption, replacement_lot: TaxLot replacement_lot.adjusted_basis = replacement_lot.adjusted_basis + disallowed consumption.realized_gain_loss = consumption.realized_gain_loss + disallowed - # S6 §4: react to the wash-sale-adjustment entry just posted, same transaction, same - # session (RestatementService.restate() must see this not-yet-committed correction). + # S6 §4: restate in the same transaction so it sees the uncommitted correction. RestatementService( self._uow, fee_disclosure_checker=FeeRestatementDisclosureService(self._uow) ).restate( diff --git a/backend/app/services/ops/audit_sink.py b/backend/app/services/ops/audit_sink.py index 6fc6617..595f468 100644 --- a/backend/app/services/ops/audit_sink.py +++ b/backend/app/services/ops/audit_sink.py @@ -1,9 +1,4 @@ -"""The concrete `AuditSink` (`app/core/security.py`) backed by `admin_audit_log` (S0 §7.2). - -Lives in `app/services/` rather than `app/core/` because it imports the concrete -`AdminAuditLog` model — exactly the dependency `core/security.py`'s `AuditSink` Protocol exists -to invert. Installed once at startup via `app.core.security.set_audit_sink()`. -""" +"""Concrete `AuditSink` backed by `admin_audit_log` (S0 §7.2).""" from __future__ import annotations @@ -18,9 +13,7 @@ class SqlAuditSink: - """Stages an `AdminAuditLog` row via the append-only repository bound to the caller's - `UnitOfWork` — never its own transaction, so the audit write and the action it records - commit or roll back together.""" + """Stages an `AdminAuditLog` row on the caller's `UnitOfWork`, never its own transaction.""" def record( self, diff --git a/backend/app/services/ops/outbox_task_router.py b/backend/app/services/ops/outbox_task_router.py index 9a2ffff..24fc41b 100644 --- a/backend/app/services/ops/outbox_task_router.py +++ b/backend/app/services/ops/outbox_task_router.py @@ -1,15 +1,5 @@ -"""`OutboxTaskRouter` -- the composition point that fans a claimed `job_outbox` row out to the -handler for its `task`, matching `OutboxTaskHandler`'s shape (`app/workers/outbox.py`) so an -`OutboxWorker` can be constructed with exactly one handler regardless of how many task types this -codebase's services actually enqueue (`grep -rn "outbox.enqueue(" app/services/` currently finds -three: `submit_order_to_broker`, `charge_fee`, `process_inbound_event`). - -Deliberately separate from the CLI wiring that constructs its routes (`app/jobs/__init__.py`'s -`outbox-worker` command): that wiring needs real database/broker/payment credentials and cannot be -unit tested without them, the same way `daily_valuation_command`'s own credential gating is -untested inline CLI logic elsewhere in this file -- but *which task routes to which callable* is -ordinary, DB-free logic with no reason to share that untestability, so it lives here instead. -""" +"""Fans a claimed `job_outbox` row out to the handler for its `task`, matching `OutboxTaskHandler`'s +shape (`app/workers/outbox.py`).""" from __future__ import annotations @@ -20,9 +10,7 @@ class UnregisteredOutboxTaskError(RuntimeError): - """Raised rather than silently dropping a claimed row whose task has no route -- an outbox - row with no handler is a wiring gap, not a no-op (the same reasoning - `InboundEventDispatcher.UnregisteredSourceError` already states for its own, narrower case).""" + """Raised when a claimed row's task has no route -- a wiring gap, not a no-op.""" class OutboxTaskRouter: diff --git a/backend/app/services/orders/approval_hold_service.py b/backend/app/services/orders/approval_hold_service.py index eb18e04..a132bc9 100644 --- a/backend/app/services/orders/approval_hold_service.py +++ b/backend/app/services/orders/approval_hold_service.py @@ -1,12 +1,6 @@ -"""`ApprovalHoldService` (S3 §3.3/§4) — opens and releases the cash hold behind an order's -approval-pending/approved-not-yet-submitted window. - -`release()` is idempotent by design (S3 §7 case 5): a `rejected`/`canceled`/`expired`/`submitted` -event for an order with no active hold (already released, or never held because it was below -threshold) is a no-op, never an error that could block folding the event that triggered it. Every -caller runs this inside the same `UnitOfWork`/transaction as the `order_event` insert and the -`order` projection update it accompanies (FR-38) — this service never opens its own transaction or -commits. +"""Opens and releases the cash hold behind an order's approval window (S3 §3.3/§4). + +`release()` is idempotent (S3 §7 case 5); never opens its own transaction or commits. """ from __future__ import annotations @@ -34,9 +28,7 @@ def __init__(self, uow: OrdersUnitOfWork) -> None: def open( self, *, order_id: uuid.UUID, customer_id: uuid.UUID, amount_money: Money ) -> ApprovalHold: - """Create the one hold row an order will ever have (`order_id` is unique, S3 §3.3). - Callers acquire the per-customer cash lock (S1 §3.5) before calling this, in the same - transaction, per foundation spec §10 case 1.""" + """Create the one hold row an order will ever have (`order_id` is unique, S3 §3.3).""" hold = ApprovalHold(order_id=order_id, customer_id=customer_id, amount_money=amount_money) self._uow.approval_holds.add(hold) return hold diff --git a/backend/app/services/orders/holds_provider.py b/backend/app/services/orders/holds_provider.py index 09d7afc..4fb9cf6 100644 --- a/backend/app/services/orders/holds_provider.py +++ b/backend/app/services/orders/holds_provider.py @@ -1,18 +1,7 @@ -"""`OrderHoldsProvider` — the real `CashPolicyService.HoldsProvider` (S1 §5) S3 owns implementing. - -Replaces `app.services.identity.null_holds_provider.NullHoldsProvider` at its wiring point -(`app/controllers/api/funding.py`) — funding-engineer's stand-in, not this module's to swap in, -since that controller is outside this sub-project's file set. - -`open_buy_commitments`'s valuation of a still-open buy order's *unfilled* remainder is a judgment -call worth a second look: once a fill exists, `average_fill_price` is a real execution price and -values the remainder off it; before any fill, the order carries no price of its own (S3 §3.1's -schema has none), so this falls back to the order's own `approval_hold.amount_money` — the -notional estimate computed at order-creation time, still on that row even after release -(`approval_hold` is not append-only; a released row is simply no longer `active`, never deleted). -Reusing it here means an unfilled order is never valued at zero while it is genuinely committing a -customer's cash to a pending buy, without inventing a new persisted column this design doesn't -already have. +"""The real `CashPolicyService.HoldsProvider` implementation (S1 §5), owned by S3. + +Values an unfilled buy's remainder off `average_fill_price` once filled, else the order's +own `approval_hold.amount_money` notional estimate. """ from __future__ import annotations @@ -29,11 +18,7 @@ class _OrdersAndHoldsUnitOfWork(Protocol): - """The minimal structural surface `OrderHoldsProvider` needs -- `OrdersUnitOfWork` satisfies - it, and so does `FundingUnitOfWork` (`app/controllers/api/funding.py`'s own wiring point, per - this module's original docstring) once it exposes the same two repositories. A concrete - `OrdersUnitOfWork` annotation here would force `funding.py` onto a UnitOfWork built for a - different sub-project's whole transaction shape just to reuse two repository accessors.""" + """Satisfied by `OrdersUnitOfWork` and by `FundingUnitOfWork`.""" @property def orders(self) -> OrderRepository: ... diff --git a/backend/app/services/orders/order_projection_service.py b/backend/app/services/orders/order_projection_service.py index 702168f..23cd3a2 100644 --- a/backend/app/services/orders/order_projection_service.py +++ b/backend/app/services/orders/order_projection_service.py @@ -1,14 +1,6 @@ -"""`OrderProjectionService` (S3 §3.1/§3.2, ADR 7) — folds `order_event` by `seq` into `order`'s -cached `status`/`filled_quantity`/`average_fill_price`. - -`fold()` is a pure function deliberately kept independent of any `UnitOfWork` so -`tests/integration`'s property-based suite can call it directly over generated event sequences and -assert `fold(events) == ` (S3 §8) with no database involved. -`OrderProjectionService` wraps it with the side effects a real event arrival needs: persisting the -new event, rebuilding the whole projection from every event on file (never an incremental "apply -one event onto the existing projection" step, precisely because that would get the wrong answer -under reordering — foundation spec §10 case 4), and releasing the approval hold in the same -transaction the instant the resulting status warrants it (FR-38, S3 §4's last paragraph). +"""Folds `order_event` by `seq` into `order`'s cached status/fill fields (S3 §3.1/§3.2, ADR 7). + +`fold()` is a pure function; `OrderProjectionService` wraps it with persistence and hold release. """ from __future__ import annotations @@ -46,9 +38,7 @@ class OrderProjectionState: def fold(events: Sequence[OrderEvent], *, quantity_requested: Units) -> OrderProjectionState: - """The standing invariant's right-hand side: `assert projection == fold(order_event)` (S3 - §3.1). Sorts by `seq` first, so the result depends only on the events given, never the order - they were passed in or persisted in (foundation spec §10 case 4).""" + """`assert projection == fold(order_event)` (S3 §3.1); sorts by `seq` first.""" status = OrderStatus.APPROVED filled_quantity = Units("0") total_notional = Money("0.00") @@ -96,14 +86,7 @@ def __init__( self._now = now def apply_new_event(self, order: Order, event: OrderEvent) -> OrderProjectionState: - """Persist `event`, rebuild `order`'s projection from every event now on file, and - release the approval hold in the same transaction if the resulting status warrants it. - - Safe to call repeatedly with events that resolve to the same terminal/`submitted` status - more than once (e.g. a rebuild triggered by a later, unrelated event) -- - `ApprovalHoldService.release` is idempotent (S3 §7 case 5), so this never double-releases - or errors on an already-released hold. - """ + """Persist `event`, rebuild the projection from every event on file, release the hold if warranted.""" self._uow.order_events.add(event) self._uow.session.flush() events = self._uow.order_events.list_for_order(order.id) diff --git a/backend/app/services/orders/order_service.py b/backend/app/services/orders/order_service.py index 7d4b1fc..f70d065 100644 --- a/backend/app/services/orders/order_service.py +++ b/backend/app/services/orders/order_service.py @@ -1,21 +1,7 @@ -"""`OrderService` (S3 §4/§6/§7) — the order state machine: creation with the FR-10 approval -threshold, explicit customer approval, and broker submission with S3 §7 case 2's re-check. - -**`OrderCreationRequest.reference_price` is a judgment call worth a second look** (flagged in this -sub-project's escalation, not yet resolved as of this writing): `order`'s schema (S3 §3.1) has no -price field, but both the FR-10 threshold check and `approval_hold.amount_money` (S3 §3.3) need a -dollar notional before any fill exists. This service takes that price from the caller rather than -reaching for a market-data dependency S3 doesn't otherwise have (`ports.py`'s `MarketDataPort` is -S4's) — every real caller already has one in hand: a customer's order-entry screen necessarily -shows a price, and S9's `RebalanceOrderService` already has one from S4's valuation to size -`quantity` in the first place. Used only in memory, never persisted on `order`. - -**`symbol` travels through the outbox payload, not a new `order` column** -- `enqueue_submission` -resolves it from S5's securities catalogue (`order.security_id`) at enqueue time, never taking it -from a caller. It was originally caller-supplied because no securities catalogue existed yet when -this module was written; now that S5 has built one, requiring `POST /orders//approve` to -resupply a symbol the customer's own approve action never had in the first place was a real, -unnecessary gap (frontend escalation), closed by resolving it here instead. +"""Order state machine: creation with FR-10's approval threshold, approval, broker submission (S3 §4/§6/§7). + +`reference_price` is caller-supplied, used only in memory. `symbol` resolves from S5's +securities catalogue at enqueue time, never from the caller. """ from __future__ import annotations @@ -49,8 +35,7 @@ class CustomerNotEligibleError(RuntimeError): - """KYC/account-approval gate not satisfied (S2 dependency; S3 §7 case 2). `reason` names the - specific gate, matching `DepositService.FundingNotEligibleError`'s own shape (S2).""" + """KYC/account-approval gate not satisfied (S3 §7 case 2); `reason` names the specific gate.""" def __init__(self, reason: str) -> None: super().__init__(f"customer is not eligible to place or submit orders: {reason}") @@ -58,10 +43,7 @@ def __init__(self, reason: str) -> None: class InsufficientInvestableCashError(RuntimeError): - """S0 §10.1/ADR 5: a buy's notional exceeds `CashPolicyService.investable` -- checked here, - not only implied by the hold, matching `WithdrawalService.InsufficientWithdrawableCashError`'s - own shape (S2). A sell never reaches this check (`side` gates it below): a sell can only ever - reduce a position the customer already has lots for, so it has no cash precondition.""" + """A buy's notional exceeds `CashPolicyService.investable` (S0 §10.1/ADR 5).""" def __init__(self, *, notional: Money, investable: Money) -> None: super().__init__(f"order notional {notional} exceeds investable cash {investable}") @@ -74,9 +56,7 @@ class OrderNotFoundError(RuntimeError): class SecurityNotFoundError(RuntimeError): - """`order.security_id` names no row in the securities catalogue -- should not happen given the - FK, defensive only (`Order.security_id` has no `ForeignKeyConstraint` at the DB level yet, per - S3's own schema, so this is the one place that gap could actually surface).""" + """`order.security_id` names no row in the securities catalogue; defensive only.""" class InvalidOrderTransitionError(RuntimeError): @@ -93,7 +73,7 @@ class OrderCreationRequest: side: OrderSide quantity: Units reference_price: Price - """See module docstring -- used only to size the threshold check and the hold, never stored.""" + """Used only to size the threshold check and the hold; never stored.""" class OrderService: @@ -113,13 +93,7 @@ def __init__( self._now = now def create_order(self, request: OrderCreationRequest) -> Order: - """S3 §4's `draft -> awaiting_approval | approved` transition, plus the hold both - branches need (S3 §4's last paragraph: `awaiting_approval` and `approved`-not-yet- - `submitted` both hold). Acquires the per-customer cash lock first (foundation spec §10 - case 1), then -- for a buy -- checks the notional against investable cash (S0 §10.1: "the - write" was already correct, "the check" was not; a sell has no cash precondition, only a - lot-quantity one enforced downstream at fill time). Does not commit -- the caller's - transaction boundary decides that.""" + """S3 §4's `draft -> awaiting_approval | approved` transition, plus the hold. Does not commit.""" self._require_eligible_customer(request.customer_id) self._uow.cash_locks.acquire(request.customer_id) @@ -146,16 +120,14 @@ def create_order(self, request: OrderCreationRequest) -> Order: client_order_id=derive_client_order_id(order_id), ) self._uow.orders.add(order) - self._uow.session.flush() # order.id must exist in the database before approval_hold's FK + self._uow.session.flush() # order.id must exist before approval_hold's FK self._hold_service.open( order_id=order_id, customer_id=request.customer_id, amount_money=notional ) return order def approve(self, order_id: uuid.UUID) -> Order: - """S3 §4/§6: `awaiting_approval -> approved`, the customer's explicit FR-10 approval. - Ownership/authentication is the controller's job (`@requires_ownership`); this method - only enforces the state-machine transition itself.""" + """S3 §4/§6: `awaiting_approval -> approved`, the customer's explicit FR-10 approval.""" order = self._uow.orders.get_for_update(order_id) if order is None: raise OrderNotFoundError(f"no order found for id={order_id!r}") @@ -165,17 +137,9 @@ def approve(self, order_id: uuid.UUID) -> Order: return order def enqueue_submission(self, order: Order) -> None: - """Enqueues the outbox task that actually calls the broker -- `submitted` only fires once - that call succeeds (S3 §4), never at the moment this intent is persisted. - - Resolves `symbol` from S5's securities catalogue (`order.security_id`) rather than taking - it from the caller -- the module docstring's original reason for a caller-supplied symbol - ("no securities catalogue to resolve against yet") no longer holds now that S5 has built - one; requiring every caller (a customer's own approve action, in particular) to already - know and resupply a symbol it was never given in the first place was the actual gap this - closes (frontend escalation).""" + """Enqueues the broker-submission outbox task; resolves `symbol` from S5's securities catalogue.""" security = self._uow.securities.get_by_id(order.security_id) - if security is None: # pragma: no cover - defensive; see SecurityNotFoundError docstring + if security is None: # pragma: no cover - defensive raise SecurityNotFoundError(f"no security found for id={order.security_id!r}") self._uow.outbox.enqueue( "submit_order_to_broker", {"order_id": str(order.id), "symbol": security.symbol} @@ -183,16 +147,12 @@ def enqueue_submission(self, order: Order) -> None: self._uow.notify_outbox_ready() def submit_to_broker(self, order_id: uuid.UUID, *, symbol: str, broker: BrokerPort) -> None: - """The `submit_order_to_broker` outbox task's body (S3 §4, §7 case 2): re-checks - eligibility immediately before the broker call, since an account can be suspended between - order creation and this later, asynchronous step. A gate that has closed blocks - submission and rejects the order (releasing its hold with reason `rejected`) rather than - placing an order for a customer no longer eligible to trade.""" + """The `submit_order_to_broker` outbox task's body (S3 §4, §7 case 2): re-checks eligibility first.""" order = self._uow.orders.get_for_update(order_id) if order is None: - return # nothing to do -- should not happen, defensive only + return # defensive only if order.status is not OrderStatus.APPROVED: - return # already submitted/terminal -- a retried outbox attempt after a partial success + return # already submitted/terminal; a retried outbox attempt try: self._require_eligible_customer(order.customer_id) @@ -219,11 +179,7 @@ def submit_to_broker(self, order_id: uuid.UUID, *, symbol: str, broker: BrokerPo def _synthesize_event( self, order: Order, event_type: OrderEventType, *, payload: dict[str, Any] ) -> None: - """An `order_event` this service itself originates, not a broker-delivered one: the - `submitted` event on broker success, and the pre-submission `rejected` event when case 2's - re-check fails. Shares `seq_from_timestamp` with every other `order_event` writer - (`app.models.orders.order_event`'s own docstring) -- one ordering mechanism regardless of - source.""" + """An `order_event` this service itself originates: `submitted` or pre-submission `rejected`.""" projection = OrderProjectionService( self._uow, hold_service=self._hold_service, now=self._now ) diff --git a/backend/app/services/orders/trade_update_handler.py b/backend/app/services/orders/trade_update_handler.py index 52fd73d..30107e0 100644 --- a/backend/app/services/orders/trade_update_handler.py +++ b/backend/app/services/orders/trade_update_handler.py @@ -1,30 +1,7 @@ -"""`AlpacaTradeUpdateHandler` — the `InboundEventDispatcher` route for -`InboundEventSource.ALPACA` (S0 §6's shared dispatch; ADR 22). - -Registered via `dispatcher.register(InboundEventSource.ALPACA, handler.handle)` at application -wiring time (`app/services/intake/dispatch.py`'s own module docstring names this as "not yet wired -end-to-end" -- each track's tests exercise `handle()` directly, matching that note; the actual -`dispatcher.register(...)` call is application-startup wiring, owned wherever the rest of that -wiring happens). - -**A second, minimal validation model, not the one `TradeUpdatesConsumer` uses.** Reusing that one -directly would require this module (`app/services/`) to import -`app/integrations/alpaca/trade_updates_consumer.py`, which `.importlinter`'s -`services-use-ports-only` contract forbids outright (services reach providers only through -`Protocol`s in `ports.py`, never a concrete integration module). The payload already passed that -model's validation once, at intake (foundation spec §6) -- this smaller one exists only so a -malformed row surfaces a clear `ValidationError` here too, rather than a bare `KeyError` deep in -dict access. - -**A `fill`/`partial_fill` event also drives S5's `LotConsumptionService`** (S3's own non-goals -list: "tax lot consumption on a sell fill -- S5"; a buy fill opening a lot is the same seam). -`market_clock` is a factory, not a ready `MarketClock`, because the real (`CachedTradingCalendar`) -calendar reads `market_calendar_cache` through a repository bound to *this* call's `uow` -- a -`MarketClock` built once at handler-construction time would hold a stale, already-closed session -by the second `handle()` call. The default factory matches -`app/controllers/api/valuation.py`'s own `MarketClock(CachedTradingCalendar(uow.calendar_cache))` -construction; a test substitutes a trivial in-memory calendar instead of seeding -`market_calendar_cache` rows. +"""`InboundEventDispatcher` route for `InboundEventSource.ALPACA` (S0 §6, ADR 22). + +Validates independently of `TradeUpdatesConsumer` (import-linter forbids the cross-layer +import); a `fill`/`partial_fill` event also drives S5's `LotConsumptionService`. """ from __future__ import annotations @@ -62,9 +39,7 @@ def _default_market_clock_factory(uow: OrdersUnitOfWork) -> MarketClock: "expired": OrderEventType.EXPIRED, "rejected": OrderEventType.REJECTED, } -"""Mirrors `trade_updates_consumer._HANDLED_EVENTS`' mapping intent -- duplicated rather than -imported for the layering reason in the module docstring; see that module for the full rationale -(Alpaca's `new` vs this system's `accepted`, `fill`/`partial_fill` both collapsing to `FILL`).""" +"""Mirrors `trade_updates_consumer._HANDLED_EVENTS`; duplicated to respect the layering rule.""" class _AlpacaTradeUpdateOrder(BaseModel): @@ -86,18 +61,11 @@ class _AlpacaTradeUpdatePayload(BaseModel): class OrderNotFoundForClientOrderIdError(RuntimeError): - """No `order` row matches the incoming message's `client_order_id` -- foundation spec §10 - case 4's "event referencing an entity the system does not yet know about." Raised rather than - silently dropped; the outbox worker's own retry-then-dead-letter (`app/workers/outbox.py`) is - what "parked... surfaced for operator attention" resolves to here, since this handler has no - other channel back to `inbound_event.status` (the dispatcher that calls it does, not this - module -- see `app/services/intake/dispatch.py`, not this sub-project's file).""" + """No `order` row matches the incoming `client_order_id` (foundation spec §10 case 4).""" class InvalidFillPayloadError(RuntimeError): - """A `fill`/`partial_fill` event arrived with no `execution_id`/`qty`/`price` -- a broker - contract violation (ADR 7's dedupe key and S5's lot-opening/consumption both require all - three), not a state this handler can proceed past.""" + """A `fill`/`partial_fill` event arrived with no `execution_id`/`qty`/`price`.""" class AlpacaTradeUpdateHandler: diff --git a/backend/app/services/orders/uow.py b/backend/app/services/orders/uow.py index ad0a64e..cb7ebb9 100644 --- a/backend/app/services/orders/uow.py +++ b/backend/app/services/orders/uow.py @@ -1,19 +1,5 @@ -"""`OrdersUnitOfWork` — composes `IdentityUnitOfWork` (KYC/account-approval gate checks, S3 §7 -case 2), `LedgerUnitOfWork` (S1: a fill posts a `trade_buy`/`trade_sell` entry, and a hold -acquires the same per-customer cash-lock row a withdrawal or fee charge would, foundation spec -§10 case 1; S5 adds `tax_lots`/`lot_consumptions`/`wash_sale_adjustments` to this same mixin), -`OpsUnitOfWork` (enqueueing the `submit_order_to_broker` outbox task, S3 §4; also `inbound_events`, -for S5's synthesized-event-per-posting pattern), and `MarketDataUnitOfWork` (S5's fill-integration -needs `calendar_cache` for the `MarketClock` a trade's T+1 settlement/designation-window -computation requires -- the same reason `ValuationUnitOfWork` composes it) onto one transaction -boundary, plus S3's own `orders`/`order_events`/`approval_holds`/`idempotency_keys` repositories. - -The identical composed-via-multiple-inheritance pattern `FundingUnitOfWork` (S2) already -establishes for the same shape of problem (S0 §5's documented extension mechanism) -- and lives -here, in `app/services/`, rather than `app/models/orders/`, for the same reason -`FundingUnitOfWork` does: it depends on `IdentityUnitOfWork`, which is itself a services-layer -module, and `app/models/` may not import `app/services/` (S0 §3). -""" +"""Composes `IdentityUnitOfWork`, `LotsUnitOfWork`, and `MarketDataUnitOfWork` with S3's own +repositories.""" from __future__ import annotations diff --git a/backend/app/services/rebalance/drift_evaluation_service.py b/backend/app/services/rebalance/drift_evaluation_service.py index e29dc91..3926399 100644 --- a/backend/app/services/rebalance/drift_evaluation_service.py +++ b/backend/app/services/rebalance/drift_evaluation_service.py @@ -1,17 +1,8 @@ -"""`DriftEvaluationService` (S9 §4) — evaluates one customer's current holdings against their -assigned model's target weights, on a **relative** tolerance band (S9 §5: a 20%-target holding -triggers at 19%/21%, not a flat +/-5 percentage-point band). - -`evaluate()` never drives a trading decision off a `partial` valuation (S9 §4's explicit -requirement, composing with S4's own completeness flag): a `partial` `value_book`, or a missing -close for any security the assigned model targets, both make the whole evaluation `partial` with -no entries at all -- never a subset silently evaluated against incomplete prices. - -Every target-weight security is priced directly from `daily_close` here (not only inferred through -`ValuationService.value_book`'s total), because a security the model targets but the customer does -not yet hold at all (the very first rebalance for a newly assigned customer, S9 §6's first-buy -case) never appears in `value_book`'s own position loop -- its price is only ever needed here, on -this path. +"""Evaluates one customer's holdings against their model's target weights on a relative band +(S9 §4/§5). + +`evaluate()` never drives a trading decision off a `partial` valuation; a missing close for +any targeted security makes the whole evaluation `partial` with no entries. """ from __future__ import annotations @@ -35,17 +26,13 @@ class NoAssignedModelError(RuntimeError): - """Raised when `evaluate()` is called for a customer with no `customer_model_assignment` - row. `MonthlyRebalanceJob` (S9 §7) only ever calls this for customers it already knows are - assigned -- this is a defensive guard, not an expected control-flow branch.""" + """Raised when `evaluate()` is called for a customer with no `customer_model_assignment` row.""" @dataclass(frozen=True, slots=True) class DriftEntry: - """One holding evaluated against its target -- `security_id is None` means the implicit CASH - holding (S9 §4's last line). `is_flagged`/`direction` are always populated, even for an - unflagged entry, so the admin visibility endpoint (foundation spec §13's `admin/rebalance.py`) - can show "how close," not just "in/out of band.""" + """One holding evaluated against its target; `security_id is None` means implicit CASH + (S9 §4).""" security_id: uuid.UUID | None current_market_value: Money @@ -65,8 +52,7 @@ class DriftEvaluation: completeness: Completeness total_value: Money entries: tuple[DriftEntry, ...] - """Empty iff `completeness == "partial"`, or the book carries no value at all (S9 §8: nothing - to rebalance against zero value, not an error).""" + """Empty iff `completeness == "partial"`, or the book carries no value at all (S9 §8).""" @property def flagged(self) -> tuple[DriftEntry, ...]: @@ -87,10 +73,7 @@ def evaluate(self, customer_id: uuid.UUID, as_of_date: date) -> DriftEvaluation: book = self._valuation.value_book(customer_id, as_of_date) if book.completeness != "complete" or book.total_value == Money("0.00"): - # A partial valuation is never traded against (S9 §4); a zero-value book has no - # weight concept at all, and is treated the same way -- nothing to rebalance, not an - # error (S9 §8's own framing for the "everything within band" case, applied here to - # an equally quiescent starting state). + # A partial valuation is never traded against (S9 §4); zero value is a no-op too. return DriftEvaluation( customer_id=customer_id, model_portfolio_id=model_portfolio_id, @@ -114,9 +97,7 @@ def evaluate(self, customer_id: uuid.UUID, as_of_date: date) -> DriftEvaluation: security_id=target.security_id, market_date=as_of_date ) if close is None: - # This security's price is unavailable on this date -- exactly the "never trade - # off an incomplete price" rule S4 enforces for held positions, extended here to - # a target the customer may not even hold yet. + # Price unavailable on this date; never trade off an incomplete price (S4). return DriftEvaluation( customer_id=customer_id, model_portfolio_id=model_portfolio_id, @@ -138,9 +119,7 @@ def evaluate(self, customer_id: uuid.UUID, as_of_date: date) -> DriftEvaluation: ) accounted_target_pct += target.weight_pct - # A held security with no target at all in the current model (S9 §8 item 4: dropped from - # the model, or never in it) -- a zero implicit target, always a full-exit sell once - # flagged (the zero-target branch inside _build_entry). + # A held security dropped from the model gets a zero implicit target (S9 §8 item 4). for security_id, units_held in current_units.items(): if security_id in seen_security_ids: continue @@ -167,9 +146,7 @@ def evaluate(self, customer_id: uuid.UUID, as_of_date: date) -> DriftEvaluation: ) ) - # The implicit CASH holding against its implicit target (S9 §4's last line): whatever - # fraction of the model the named securities do not already claim, typically 0 for a - # fully-invested model. + # The implicit CASH holding against its implicit target (S9 §4's last line). cash_target_pct = Decimal("1") - accounted_target_pct entries.append( self._build_entry( @@ -225,18 +202,7 @@ def is_out_of_band( target_weight_pct: Decimal, drift_band_pct: Decimal, ) -> bool: - """The pure comparison at the center of S9 §4/§5, isolated so the property table S9 §9 - calls for (exactly-at-target, the band-edge boundary, the zero-target branch) is unit - testable with no database, and no `Money`/`Units`/`Price`, at all -- plain `Decimal` in, - `bool` out. - - `> band` triggers; `== band` does not (S9 §9's documented boundary, tested at both edges). - A zero target weight (S9 §8 item 4: dropped from the model) has no ratio to take a - *relative* drift against -- it is flagged whenever anything is actually held (a nonzero - `current_weight_pct`, since `total_value != 0` is already guaranteed by the only caller), - and never otherwise, matching the spec's "always a 100%-relative drift" framing without - dividing by zero to get there. - """ + """Pure relative-drift comparison (S9 §4/§5): `> band` triggers, `== band` does not.""" if target_weight_pct == 0: return current_weight_pct != 0 relative_drift = (current_weight_pct - target_weight_pct) / target_weight_pct diff --git a/backend/app/services/rebalance/rebalance_order_service.py b/backend/app/services/rebalance/rebalance_order_service.py index 7f9802d..916fea5 100644 --- a/backend/app/services/rebalance/rebalance_order_service.py +++ b/backend/app/services/rebalance/rebalance_order_service.py @@ -1,27 +1,8 @@ -"""`RebalanceOrderService` (S9 §6) — turns a `DriftEvaluation`'s flagged entries into orders, -sells before buys, sized to close each holding's drift to zero (not to the band edge) and capped -by a cash buffer on the buy side. - -Depends on two narrow `Protocol`s, `OrderPlacer`/`InvestableCashProvider`, rather than the concrete -`OrderService`/`CashPolicyService` directly (S0 §5's own precedent: "services depend on their -aggregate's own Protocol... a test substitutes a fake by implementing that Protocol structurally"). -That is what makes S9 §9's unit-level tests -- sells-before-buys ordering, the cash-buffer sizing -arithmetic, the buffer-drives-a-buy-to-zero edge case (S9 §8 item 5) -- runnable with no database at -all; `_RealOrderPlacer` below is the thin adapter the job/controller wires the real `OrderService` -through. - -No `designation_override` is ever passed (S5 §4/ADR 4: a system-generated sell always takes the -FIFO branch, since no investor is present to elect lots) -- this falls out for free, since -`OrderCreationRequest` (S3 §3.1) has no such field to begin with; there is nothing here that could -set one. - -A rebalance order above `order_approval_threshold_usd` lands in `awaiting_approval` exactly like a -customer-placed order would (S9 §6: "identical to a customer order") -- this service only enqueues -broker submission when `OrderService.create_order` already auto-approved it; an -`awaiting_approval` rebalance order simply waits for the owning customer's own -`POST /orders//approve`, the same endpoint and the same state machine a customer-initiated -order above threshold already goes through. No second approval path is introduced for a -system-generated order. +"""Turns a `DriftEvaluation`'s flagged entries into orders, sells before buys, capped by a +cash buffer (S9 §6). + +Depends on narrow `OrderPlacer`/`InvestableCashProvider` `Protocol`s rather than the concrete +services, so S9 §9's unit tests run with no database. """ from __future__ import annotations @@ -42,8 +23,7 @@ class OrderPlacer(Protocol): - """The minimal surface `RebalanceOrderService` needs to place one order -- satisfied by - `_RealOrderPlacer` (this module) in production, and by a plain recording fake in a unit test.""" + """The minimal surface `RebalanceOrderService` needs to place one order.""" def place( self, @@ -61,9 +41,8 @@ def investable(self, customer_id: uuid.UUID) -> Money: ... class _RealOrderPlacer: - """Adapter over the real `OrderService` (S3) -- `create_order` plus the same conditional - `enqueue_submission` every customer-order controller route already applies (only when - auto-approved; see this module's own docstring for the `awaiting_approval` case).""" + """Adapter over the real `OrderService` (S3): `create_order` plus conditional + `enqueue_submission`.""" def __init__(self, order_service: OrderService) -> None: self._order_service = order_service @@ -108,11 +87,8 @@ def __init__( self._cash_buffer_pct = cash_buffer_pct def generate_orders(self, evaluation: DriftEvaluation) -> list[Order]: - """S9 §6's pseudocode exactly: sells first (never fund a buy from this run's own - unsettled sell proceeds racing, S9 §6's own reasoning), then buys capped by the cash - buffer. The implicit CASH entry (`security_id is None`) never itself produces an order -- - cash is not a tradeable security; its flag exists only for the admin visibility endpoint - (`DriftEvaluationService`'s own docstring).""" + """S9 §6: sells first, then buys capped by the cash buffer. CASH entries never produce + an order.""" security_flags = [entry for entry in evaluation.flagged if entry.security_id is not None] if not security_flags: return [] @@ -130,8 +106,7 @@ def generate_orders(self, evaluation: DriftEvaluation) -> list[Order]: buffer = evaluation.total_value * self._cash_buffer_pct available = self._cash_provider.investable(evaluation.customer_id) - buffer if available <= Money("0.00"): - # The buffer alone consumes all headroom -- S9 §8 item 5's documented outcome: a - # smaller (here, zero) buy, never an error. + # The buffer alone consumes all headroom (S9 §8 item 5): a zero buy, never an error. return orders remaining = available @@ -169,8 +144,7 @@ def _place_buy( return None quantity = self._quantity_for(notional, entry.price) if quantity == Units("0"): - # S9 §8 item 5: a buffer- or cap-driven notional too small to round to a nonzero - # fractional share (Units' six decimal places) -- a smaller trade, not an error. + # Notional too small to round to a nonzero fractional share (S9 §8 item 5). return None return self._order_placer.place( customer_id=customer_id, @@ -182,9 +156,7 @@ def _place_buy( @staticmethod def _quantity_for(notional: Money, price: Price) -> Units: - """S9 §5: "the exact fractional quantity needed to close the drift to zero... rounded to - `Units`'s six decimal places" -- `notional / price`, quantized to 6dp by `Units.__init__` - itself (ADR 16).""" + """S9 §5: `notional / price`, quantized to 6dp by `Units.__init__` (ADR 16).""" return notional / price diff --git a/backend/app/services/rebalance/uow.py b/backend/app/services/rebalance/uow.py index 5935fec..3115a01 100644 --- a/backend/app/services/rebalance/uow.py +++ b/backend/app/services/rebalance/uow.py @@ -1,18 +1,4 @@ -"""`RebalanceUnitOfWork` — S9 needs `RebalanceModelsUnitOfWork` (`model_portfolio`, -`target_weight`, `customer_model_assignment`), `ValuationUnitOfWork` (S4's `LedgerUnitOfWork` + -`MarketDataUnitOfWork`, for `DriftEvaluationService`'s `ValuationService` + direct `daily_closes` -reads), and `OrdersUnitOfWork` (S3's `OrderService`, the one path a rebalance order is ever -submitted through — S9 §6's "identical to a customer order, no parallel mechanism"). Composes all -three rather than duplicating their repository accessors (S0 §5's extension mechanism), the -identical multiple-inheritance shape `LotsUnitOfWork`/`OrdersUnitOfWork` already establish for the -same kind of cross-aggregate consumer. - -`OrdersUnitOfWork` already carries `LedgerUnitOfWork`/`MarketDataUnitOfWork` transitively (via -`LotsUnitOfWork`), so `ValuationUnitOfWork` adds nothing new here beyond the *nominal* type -`ValuationService.__init__(uow: ValuationUnitOfWork)` requires -- without it, passing this -`UnitOfWork` to `ValuationService` would only be structurally compatible, which `mypy --strict` -does not accept for a concrete (non-`Protocol`) parameter type. -""" +"""S9 UoW: composes `OrdersUnitOfWork`, `ValuationUnitOfWork`, and `RebalanceModelsUnitOfWork`.""" from __future__ import annotations diff --git a/backend/app/services/reconciliation/internal_state.py b/backend/app/services/reconciliation/internal_state.py index f75a969..8b6ebb2 100644 --- a/backend/app/services/reconciliation/internal_state.py +++ b/backend/app/services/reconciliation/internal_state.py @@ -1,12 +1,5 @@ -"""Internal-state readers shared by `ReconciliationService` (the matching side, S7 §6) and -`CustodianFileSimulatorAdapter` (the baseline-generation side, S7 §9) -- both need "what does -Trueup's own ledger currently say," and duplicating that read independently in each would risk the -two silently drifting on what counts as a position/transaction. - -Adapted from `DailyValuationJob._securities_with_positions`'s `Account`/`Posting`/`JournalEntry` -join (S4), grouped per `(customer_id, security_id)` instead of `security_id` alone since S7's match -grain is per-customer (S7 §4), not whole-book. -""" +"""Internal-state readers shared by `ReconciliationService` and `CustodianFileSimulatorAdapter` +(S7 §6/§9).""" from __future__ import annotations @@ -38,9 +31,7 @@ JournalEntryType.FEE_ADJUSTMENT, } ) -"""S7 §4's "every S1 journal entry that has an external counterpart" -- a correction, split, or -wash-sale adjustment is an internal-only bookkeeping act with no independent custodian-side -transaction id, so those entry types are never expected to have a custodian file counterpart.""" +"""Every S1 journal entry with an external counterpart (S7 §4).""" @dataclass(frozen=True, slots=True) @@ -57,9 +48,8 @@ class InternalTransactionSnapshot: def read_internal_positions( uow: ReconciliationUnitOfWork, market_date: date ) -> dict[tuple[uuid.UUID, uuid.UUID], Units]: - """Every nonzero `(customer_id, security_id)` position as of `market_date` (live), across - every customer -- an admin/worker-role query, deliberately not tenant-scoped, matching - `DailyValuationJob._securities_with_positions`'s own precedent.""" + """Every nonzero `(customer_id, security_id)` position as of `market_date`, across all + customers.""" statement = ( select( Account.customer_id, @@ -89,8 +79,8 @@ def read_customer_ids(uow: ReconciliationUnitOfWork) -> set[uuid.UUID]: def read_internal_transactions( uow: ReconciliationUnitOfWork, market_date: date ) -> dict[str, InternalTransactionSnapshot]: - """Every custodian-observable journal entry effective on `market_date`, keyed by the - `inbound_event.source_event_id` it traces back to (S7 §4's match key).""" + """Every custodian-observable journal entry effective on `market_date`, keyed by source + event id.""" statement = ( select(JournalEntry, InboundEvent.source_event_id) .join(InboundEvent, InboundEvent.id == JournalEntry.source_event_id) diff --git a/backend/app/services/reconciliation/reconciliation_service.py b/backend/app/services/reconciliation/reconciliation_service.py index 113c53e..de8fc82 100644 --- a/backend/app/services/reconciliation/reconciliation_service.py +++ b/backend/app/services/reconciliation/reconciliation_service.py @@ -1,8 +1,4 @@ -"""`ReconciliationService` (S7 §6) — the three matching loops plus the holiday short-circuit. - -Reuses `app.services.reconciliation.internal_state`'s readers (shared with the custodian-file -simulator, S7 §9) rather than re-deriving "what does Trueup's ledger currently say" independently. -""" +"""Three matching loops plus the holiday short-circuit for morning reconciliation (S7 §6).""" from __future__ import annotations @@ -48,14 +44,9 @@ def __init__( def run_morning_reconciliation( self, *, market_date: date, file_set: CustodianFileSet ) -> list[ReconciliationBreak]: - """S7 §6's pseudocode, literally: import the batch, short-circuit on a holiday (ADR 12), - then run the three independent matching loops. Stages every opened break via - `uow.reconciliation_breaks.add()` -- the caller commits (S0 §5's one-commit-per-operation - rule; this service never commits its own transaction).""" + """Imports the batch, short-circuits on a holiday (ADR 12), runs the matching loops.""" if not self._market_clock.is_trading_day(market_date): - # S7 §6/§10 case 1 (ADR 12): a holiday is never a break, full stop -- not "compared - # and found clean." No raw rows are persisted either; there was never a real morning - # file to preserve. + # A holiday is never a break (ADR 12); no raw rows persisted either. return [] import_batch_id = uuid.uuid4() diff --git a/backend/app/services/reconciliation/uow.py b/backend/app/services/reconciliation/uow.py index a273b97..7c9e666 100644 --- a/backend/app/services/reconciliation/uow.py +++ b/backend/app/services/reconciliation/uow.py @@ -1,20 +1,4 @@ -"""`ReconciliationUnitOfWork` — S7 spans five aggregates: its own (`custodian_file_row`/ -`reconciliation_break`), S1's ledger (positions/cash to compare against, and `tax_lots` for -`inject_corrected_price`'s per-customer fan-out), S0's ops spine (`inbound_events`, to synthesize -the event `RestatementService.restate()` requires a `source_event_id` for), S4's market data (the -trading calendar for the holiday short-circuit, S7 §6/ADR 12, plus `sub_period_returns`), and S6's -restatement aggregate (`published_snapshots`/`restatement_events`, via -`RestatementModelsUnitOfWork`, so `inject_corrected_price` can call `RestatementService.restate()` -in the *same* transaction as its `daily_close` write, per restatement-engineer's own -`RestatementCapableUnitOfWork` contract) — composed via multiple inheritance, the identical pattern -`ValuationUnitOfWork`/`LotsUnitOfWork` already establish for the same shape of problem (S0 §5's -documented extension mechanism). - -Named identically to `app.models.reconciliation.ReconciliationUnitOfWork` on purpose (matching -that module's own aggregate-only mixin name) — every real caller imports this module's class, not -that one directly, the same way nothing outside `app/services/orders/uow.py` imports -`MarketDataUnitOfWork` expecting `OrdersUnitOfWork`'s full repository surface. -""" +"""UoW for S7: composes reconciliation, ledger, market data, ops, and restatement mixins.""" from __future__ import annotations diff --git a/backend/app/services/restatement/restatement_service.py b/backend/app/services/restatement/restatement_service.py index 07c3149..a20117b 100644 --- a/backend/app/services/restatement/restatement_service.py +++ b/backend/app/services/restatement/restatement_service.py @@ -1,36 +1,6 @@ -"""`RestatementService` (S6 §4-5) — reacts to a correcting entry S1/S4/S5 already posted and -recomputes exactly the `sub_period_return` row(s) it touches, then re-links and cross-checks every -already-published period the correction reaches. Adds no second listening mechanism (S6 §4): -callers pass the same `effective_date`/`source_event_id` the correcting entry itself already -carries, right after posting it. - -**No producer exists yet for `manual_correction`/`corrected_close`.** `PostingService.correct()` -(S1) has zero callers today, and no code path writes a superseding `confirmed` `daily_close` row -either (`app/jobs/daily_valuation.py`'s `DailyValuationJob` only ever writes one confirmed row per -`market_date`) -- this service is ready to be called with either trigger the moment a producer -lands (S7's custodian simulator is expected to be the first, per its own spec §9), same honest- -disclosure posture S5 used for its own open items (`corporate_action_service.py`). - -**Why `RestatementService.__init__` takes a `Protocol`, not a concrete `UnitOfWork` class.** The -real trigger sites (`WashSaleService`, `CorporateActionService`) run under `LotsUnitOfWork`/ -`OrdersUnitOfWork`, not this package's own `RestatementUnitOfWork` -- and must, since recomputing a -`sub_period_return` row has to see the correcting entry's own not-yet-committed postings in the -*same* transaction (a freshly opened `UnitOfWork` would read a stale, pre-correction ledger). This -`Protocol` (S0 §5's "services depend on their aggregate's own Protocol" pattern) is what both -`RestatementUnitOfWork` and `LotsUnitOfWork` (via -`app.models.restatement.RestatementModelsUnitOfWork`, composed by both) satisfy structurally, with -no shared base class needed between them. - -**S10's own hook (§6, FR-47), added as an optional constructor dependency rather than a new -`RestatementCapableUnitOfWork` member.** Extending that `Protocol` with `fee_charges`/ -`fee_restatement_disclosures` would force every existing structural implementer -- `LotsUnitOfWork` -included, a file this sub-project does not own -- to gain those accessors too, just to keep -satisfying the `Protocol`. `fee_disclosure_checker: FeeDisclosureChecker | None = None` avoids that: -every existing call site (`WashSaleService`, `CorporateActionService`) keeps constructing -`RestatementService(self._uow)` exactly as before, unaffected. Wiring a real checker into those two -production trigger sites (`fee_disclosure_checker=FeeRestatementDisclosureService(uow)`, one extra -constructor argument each) is flagged in the fee-engineer close-out report as owed integration work -outside this sub-project's own file boundary, not silently left undone. +"""Reacts to a correcting entry, recomputes affected `sub_period_return` rows, and cross-checks +published periods (S6 §4-5). Takes a `Protocol`, not a concrete UoW, so trigger sites can recompute +within their own already-open transaction. """ from __future__ import annotations @@ -58,10 +28,7 @@ class RestatementCapableUnitOfWork(Protocol): - """The structural dependency `RestatementService`/`SnapshotService` need -- see module - docstring. `securities`/`daily_closes` are needed only for `SnapshotService._current_holdings`, - included here rather than in a second Protocol to keep one structural contract for the whole - `app/services/restatement/` package.""" + """Structural dependency `RestatementService`/`SnapshotService` need.""" @property def session(self) -> Session: ... @@ -78,12 +45,7 @@ def restatement_events(self) -> RestatementEventRepository: ... class FeeDisclosureChecker(Protocol): - """S10 §6's hook -- see module docstring for why this is an optional constructor dependency - rather than a `RestatementCapableUnitOfWork` member. The real implementation - (`app.services.fees.fee_restatement_disclosure_service.FeeRestatementDisclosureService`) checks - for a `succeeded` `fee_charge` on `[period_start, period_end]` and inserts a - `fee_restatement_disclosure` row if one is found; a no-op checker (or `None`) is exactly as - correct for a customer S10 has no fee history for.""" + """S10 §6's fee-disclosure hook, an optional constructor dependency.""" def check_and_disclose( self, @@ -114,18 +76,8 @@ def restate( trigger_type: RestatementTriggerType, source_event_id: uuid.UUID, ) -> tuple[SubPeriodReturn, ...]: - """S6 §5's pipeline. Recomputes every stored `sub_period_return` window containing - `affected_date` (usually exactly one), logs a `restatement_event` per window recomputed, - then re-links and `cross_check`s every already-published period any of those windows falls - within (S6 §6). A window that has never been published is still recomputed and logged - (S6 §9 edge case 2) -- there is simply nothing to cross-check for it yet. - - `affected_date` with no stored window containing it (S4 has never computed a TWR touching - this date) still logs one audit row, using `affected_date` itself as a degenerate - single-day period -- there is no wider window to recompute, since nothing was ever stored - for one, but the audit trail's own purpose (S6 §3.2: "why did my return change") still - applies to "we checked, and there was nothing to restate." - """ + """S6 §5's pipeline: recomputes windows containing `affected_date`, logs an audit event + per window, then re-links and cross-checks affected published periods (S6 §6).""" windows = self._uow.sub_period_returns.containing( customer_id=customer_id, on_date=affected_date ) diff --git a/backend/app/views/agent_requests.py b/backend/app/views/agent_requests.py new file mode 100644 index 0000000..2b49211 --- /dev/null +++ b/backend/app/views/agent_requests.py @@ -0,0 +1,50 @@ +"""Response schemas for `app/controllers/admin/agent_requests.py` (S13 §5). + +Explicit allow-lists only, never a raw entity (`app/views/` may not import `app/models/`, +`lint-imports`'s `views-are-not-entities` contract). +""" + +from __future__ import annotations + +import uuid # noqa: TC003 -- Pydantic resolves field annotations eagerly. +from datetime import datetime # noqa: TC003 +from typing import Any, Literal + +from pydantic import BaseModel + +AgentActionTypeLiteral = Literal["resolve_break", "kyc_override", "rebalance"] +AgentActionStatusLiteral = Literal[ + "pending", "approved", "rejected", "executed", "execution_failed" +] + + +class AgentActionRequestResponse(BaseModel): + """One `agent_action_request` row (S13 §3.1).""" + + id: uuid.UUID + action: AgentActionTypeLiteral + arguments: dict[str, Any] + requesting_agent: str + justification: str + status: AgentActionStatusLiteral + reviewed_by: uuid.UUID | None + reviewed_at: datetime | None + review_note: str | None + execution_error: str | None + executed_at: datetime | None + created_at: datetime + + +class AgentActionRequestsListResponse(BaseModel): + """`GET /api/v1/admin/agent-requests` (S13 §5) -- keyset-paginated, oldest-first.""" + + requests: list[AgentActionRequestResponse] + next_cursor: str | None + + +__all__ = [ + "AgentActionRequestResponse", + "AgentActionRequestsListResponse", + "AgentActionStatusLiteral", + "AgentActionTypeLiteral", +] diff --git a/backend/app/views/staff_api_tokens.py b/backend/app/views/staff_api_tokens.py new file mode 100644 index 0000000..d6bed32 --- /dev/null +++ b/backend/app/views/staff_api_tokens.py @@ -0,0 +1,43 @@ +"""Response schemas for `app/controllers/admin/staff_api_tokens.py` (S13 §3.2). + +Explicit allow-lists only, never a raw entity (`app/views/` may not import `app/models/`, +`lint-imports`'s `views-are-not-entities` contract). `token` is present on +`StaffApiTokenIssuedResponse` only -- the raw token is returned exactly once, at issue time, and +never appears on any other response shape in this module. +""" + +from __future__ import annotations + +import uuid # noqa: TC003 -- Pydantic resolves field annotations eagerly. +from datetime import datetime # noqa: TC003 + +from pydantic import BaseModel + + +class StaffApiTokenIssuedResponse(BaseModel): + """`POST /api/v1/admin/staff-api-tokens` -- the one and only time the raw token is returned.""" + + id: uuid.UUID + label: str + token: str + created_at: datetime + + +class StaffApiTokenSummaryResponse(BaseModel): + """One row of `GET /api/v1/admin/staff-api-tokens` -- never the raw token or its hash.""" + + id: uuid.UUID + label: str + created_at: datetime + revoked_at: datetime | None + + +class StaffApiTokensListResponse(BaseModel): + tokens: list[StaffApiTokenSummaryResponse] + + +__all__ = [ + "StaffApiTokenIssuedResponse", + "StaffApiTokenSummaryResponse", + "StaffApiTokensListResponse", +] diff --git a/backend/app/workers/outbox.py b/backend/app/workers/outbox.py index dfea592..4505430 100644 --- a/backend/app/workers/outbox.py +++ b/backend/app/workers/outbox.py @@ -1,9 +1,5 @@ -"""Postgres LISTEN/NOTIFY outbox consumer. - -The listening connection is deliberately a standalone psycopg connection, outside SQLAlchemy's -pool. It stays in autocommit mode so LISTEN registration and notification delivery are not tied to -the short UnitOfWork transactions used to claim and complete work. -""" +"""Postgres LISTEN/NOTIFY outbox consumer. The listening connection is a standalone, autocommit +psycopg connection outside SQLAlchemy's pool.""" from __future__ import annotations @@ -37,20 +33,13 @@ def retry_or_dead_letter( class OutboxUnitOfWork(Protocol): - # A `@property` here, not a bare attribute annotation: every real UnitOfWork exposes its - # repositories as `@cached_property`, and a Protocol's bare-attribute form expects a settable - # instance attribute, which a read-only property/cached_property does not structurally satisfy - # under strict mypy (the same fix `event_intake.py`'s equivalent Protocol already applies). + # @property, not a bare attribute: real UnitOfWork exposes repos as @cached_property. @property def outbox(self) -> OutboxRepository: ... def __enter__(self) -> Self: ... - # The real 3-argument context-manager `__exit__` (matching `app.core.uow.UnitOfWork`'s own - # signature exactly, the same proven pattern `event_intake.py`'s equivalent Protocol uses) -- - # a looser `*args: object` here structurally rejects any real `UnitOfWork` subclass under - # strict Protocol matching, since a subclass's narrower, concretely-typed `__exit__` cannot - # satisfy a Protocol that promises callers may pass arbitrary positional `object`s. + # Matches UnitOfWork's concrete 3-arg __exit__ signature for strict Protocol matching. def __exit__( self, exc_type: type[BaseException] | None, @@ -94,11 +83,8 @@ def __init__( self._clock = clock def drain_once(self) -> bool: - """Process one row, returning whether work was found. - - Claiming commits before handler execution. Consequently, slow provider I/O never holds the - row lock or database transaction open, and another worker cannot claim the same row. - """ + """Process one row, returning whether work was found. Claiming commits before handler + execution, so slow provider I/O never holds the row lock open.""" with self._uow_factory() as uow: row = uow.outbox.claim_next(worker_id=self._worker_id, now=self._clock()) uow.commit() diff --git a/backend/pyproject.toml b/backend/pyproject.toml index ca9207e..4a2a5a7 100644 --- a/backend/pyproject.toml +++ b/backend/pyproject.toml @@ -29,6 +29,7 @@ dependencies = [ "sqlglot>=30.18.0", "openai-agents>=0.22.0", "gunicorn>=26.2.0", + "mcp>=2.1.1", ] [dependency-groups] diff --git a/backend/tests/api/conftest.py b/backend/tests/api/conftest.py index 635533d..5259737 100644 --- a/backend/tests/api/conftest.py +++ b/backend/tests/api/conftest.py @@ -13,8 +13,7 @@ @pytest.fixture def api_app(app: Flask) -> Flask: - """`create_app()` already wires auth (blueprint + sessions/CSRF/login-manager); this fixture - is kept as the `tests/api/` entry point so a test only has to depend on one fixture name.""" + """The `tests/api/` entry point fixture, so a test depends on one fixture name.""" return app @@ -25,8 +24,7 @@ def api_client(api_app: Flask) -> FlaskClient: @pytest.fixture(autouse=True) def _reset_rate_limits(api_app: Flask) -> None: - """Flask-Limiter's storage is Redis (S0 §7.4) and outlives any one test — without a reset, an - earlier test's login attempts count toward a later test's throttling assertions.""" + """Flask-Limiter's Redis storage (S0 §7.4) outlives a test; reset so counts don't leak.""" from app.extensions import limiter with api_app.app_context(): @@ -35,23 +33,18 @@ def _reset_rate_limits(api_app: Flask) -> None: @pytest.fixture(scope="session", autouse=True) def _identity_tables(owner_engine: Engine) -> Iterator[None]: - """`customer`/`staff` on demand, the same way every other DB-touching test in this repo - creates its own tables (`tests/integration/test_ops_spine.py`'s `ops_tables` fixture) — nothing - in this project runs Alembic against the test database, so a fixture that assumed the tables - already existed left the whole `tests/api/` package unable to run at all. - """ + """Creates `customer`/`staff` on demand; nothing runs Alembic against the test database.""" Customer.__table__.create(bind=owner_engine, checkfirst=True) Staff.__table__.create(bind=owner_engine, checkfirst=True) yield None - Customer.__table__.drop(bind=owner_engine, checkfirst=True) - Staff.__table__.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + connection.execute(text(f'DROP TABLE IF EXISTS "{Customer.__table__.name}" CASCADE')) + connection.execute(text(f'DROP TABLE IF EXISTS "{Staff.__table__.name}" CASCADE')) @pytest.fixture(autouse=True) def _clean_identity_tables(owner_engine: Engine, _identity_tables: None) -> Iterator[None]: - """Controllers under test open their own real `UnitOfWork` and commit for real (unlike - `db_session`'s per-test rollback) — this truncates what they wrote so one test's registered - customer/staff rows can never leak into the next.""" + """Controllers commit for real; truncates so rows don't leak between tests.""" yield None with owner_engine.begin() as connection: connection.execute(text("TRUNCATE customer, staff RESTART IDENTITY CASCADE")) diff --git a/backend/tests/api/test_admin_customers.py b/backend/tests/api/test_admin_customers.py index 25c99ca..0c01320 100644 --- a/backend/tests/api/test_admin_customers.py +++ b/backend/tests/api/test_admin_customers.py @@ -1,7 +1,4 @@ -"""`GET /api/v1/admin/customers`, `GET /api/v1/admin/customers/`, -`GET /api/v1/admin/customers//fees` (S8 §4 rows 1/2/6) via the Flask test client: search, -the aggregated detail view (balance agreeing with `/valuation/balance`, an open break surfaced -prominently per S8 §6 case 2), the fees re-export, authn/authz, and throttling. +"""Admin customer search/detail/fees endpoints (S8 §4 rows 1/2/6) via the Flask test client. """ from __future__ import annotations diff --git a/backend/tests/api/test_admin_kyc_overrides.py b/backend/tests/api/test_admin_kyc_overrides.py index 3d4e859..365dd61 100644 --- a/backend/tests/api/test_admin_kyc_overrides.py +++ b/backend/tests/api/test_admin_kyc_overrides.py @@ -1,7 +1,5 @@ """`POST /api/v1/admin/kyc-overrides/` (S8 §4 row 5) via the Flask test client: -reopening a locked-`rejected` KYC status, validation, authz, and throttling. Confirms end-to-end -that the override actually unblocks a subsequent `POST /identity/kyc-sessions` call -(`app/services/identity/kyc_service.py`'s lock gate). +reopening a locked-rejected KYC status, validation, authz, and throttling. """ from __future__ import annotations diff --git a/backend/tests/api/test_admin_rebalance_api.py b/backend/tests/api/test_admin_rebalance_api.py index ed55b4b..4176b00 100644 --- a/backend/tests/api/test_admin_rebalance_api.py +++ b/backend/tests/api/test_admin_rebalance_api.py @@ -1,5 +1,5 @@ -"""`GET /api/v1/admin/rebalance/` (foundation spec §13's "S9 | admin/rebalance.py -(visibility only)") via the Flask test client: role-gated visibility, never a write action. +"""`GET /api/v1/admin/rebalance/` (S9, admin visibility only) via the Flask test +client. """ from __future__ import annotations @@ -39,9 +39,7 @@ STAFF_EMAIL = "admin-rebalance-adviser@trueup.example" STAFF_PASSWORD = "another-strong-password" MARKET_DATE = datetime.now(UTC).astimezone(MARKET_TIMEZONE).date() -"""Matches `MarketClock.market_date(datetime.now(UTC))`'s own computation exactly -- the -controller under test has no injectable clock, so this test's fixture data must land on -whatever "today" the controller will actually compute, not the local system date.""" +"""Matches `MarketClock.market_date()`'s own computation; the controller has no injectable clock.""" ADMIN_REBALANCE_TABLES = [ InboundEvent.__table__, @@ -128,9 +126,8 @@ def _staff_login_with_mfa(client: FlaskClient) -> None: def _seed_customer_with_holding( owner_engine: Engine, customer_id: uuid.UUID ) -> tuple[uuid.UUID, uuid.UUID]: - """100 shares of one security (@$100 = $10,000) and $0 cash left over -- exactly on target - for a model targeting that security at 100% (`target_weight`'s own sum-to-one trigger, S9 - §3.2, means cash's implicit target is always exactly 0).""" + """100 shares of one security and $0 cash left over — exactly on target for a 100% model (S9 + §3.2).""" session = Session(bind=owner_engine, expire_on_commit=False) try: customer = session.get(Customer, customer_id) diff --git a/backend/tests/api/test_agent_requests.py b/backend/tests/api/test_agent_requests.py new file mode 100644 index 0000000..ca503ae --- /dev/null +++ b/backend/tests/api/test_agent_requests.py @@ -0,0 +1,434 @@ +"""`app/controllers/admin/agent_requests.py` (S13 §5) via the Flask test client: the human +approval queue for MCP write-tool proposals, including all three execution mappings. +""" + +from __future__ import annotations + +import uuid +from collections.abc import Iterator +from datetime import UTC, datetime + +import pyotp +import pytest +from flask.testing import FlaskClient +from sqlalchemy import Engine, text +from sqlalchemy.orm import Session + +from app.models.identity.customer import AccountApprovalStatus, Customer, KycStatus +from app.models.identity.staff import Staff, StaffRole +from app.models.ops.admin_audit_log import AdminAuditLog +from app.models.ops.agent_action_request import ( + AgentActionRequest, + AgentActionStatus, + AgentActionType, +) +from app.models.rebalance.customer_model_assignment import CustomerModelAssignment +from app.models.rebalance.model_portfolio import ModelPortfolio +from app.models.reconciliation.reconciliation_break import ( + ReconciliationBreak, + ReconciliationBreakStatus, + ReconciliationBreakType, +) +from app.services.identity.auth import hash_password + +STAFF_EMAIL = "agent-requests-adviser@trueup.example" +STAFF_PASSWORD = "another-strong-password" + +_TABLES = [ + # Customer/Staff are owned by tests/api/conftest.py's session-scoped fixture, not here. + AgentActionRequest.__table__, + AdminAuditLog.__table__, + ReconciliationBreak.__table__, + ModelPortfolio.__table__, + CustomerModelAssignment.__table__, +] + + +@pytest.fixture(autouse=True) +def _tables(owner_engine: Engine) -> Iterator[None]: + for table in _TABLES: + table.create(bind=owner_engine, checkfirst=True) + yield None + with owner_engine.begin() as connection: + for table in reversed(_TABLES): + connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) + + +@pytest.fixture +def staff_member(owner_engine: Engine) -> Iterator[Staff]: + session = Session(bind=owner_engine, expire_on_commit=False) + staff = Staff( + email=STAFF_EMAIL, password_hash=hash_password(STAFF_PASSWORD), role=StaffRole.adviser + ) + session.add(staff) + session.commit() + yield staff + session.close() + + +def _staff_login_with_mfa(client: FlaskClient) -> str: + login_response = client.post( + "/api/v1/auth/login", json={"email": STAFF_EMAIL, "password": STAFF_PASSWORD} + ) + assert login_response.status_code == 200 + pending_csrf = login_response.get_json()["csrf_token"] + secret = client.post( + "/api/v1/auth/mfa/enroll", headers={"X-CSRFToken": pending_csrf} + ).get_json()["secret"] + code = pyotp.TOTP(secret).now() + verify = client.post( + "/api/v1/auth/mfa/verify", json={"code": code}, headers={"X-CSRFToken": pending_csrf} + ) + assert verify.status_code == 200 + csrf_token: str = verify.get_json()["csrf_token"] + return csrf_token + + +def _insert_customer(owner_engine: Engine) -> uuid.UUID: + with Session(bind=owner_engine, expire_on_commit=False) as session: + customer = Customer( + email=f"{uuid.uuid4()}@trueup.test", + password_hash="hash", + kyc_status=KycStatus.rejected, + account_approval_status=AccountApprovalStatus.pending, + ) + session.add(customer) + session.commit() + return customer.id + + +def _insert_break(owner_engine: Engine) -> uuid.UUID: + with Session(bind=owner_engine, expire_on_commit=False) as session: + break_row = ReconciliationBreak( + break_type=ReconciliationBreakType.CASH_MISMATCH, + customer_id=uuid.uuid4(), + opened_at=datetime.now(UTC), + status=ReconciliationBreakStatus.OPEN, + import_batch_id=uuid.uuid4(), + ) + session.add(break_row) + session.commit() + return break_row.id + + +def _insert_request( + owner_engine: Engine, + *, + action: AgentActionType, + arguments: dict[str, object], + status: AgentActionStatus = AgentActionStatus.PENDING, +) -> uuid.UUID: + """A non-`pending` row must also carry `reviewed_by`/`reviewed_at` (S13 §3.1 CHECK + constraint).""" + with Session(bind=owner_engine, expire_on_commit=False) as session: + row = AgentActionRequest( + action=action, + arguments=arguments, + requesting_agent="adviser@trueup.test (test token)", + justification="test justification", + status=status, + reviewed_by=uuid.uuid4() if status != AgentActionStatus.PENDING else None, + reviewed_at=datetime.now(UTC) if status != AgentActionStatus.PENDING else None, + ) + session.add(row) + session.commit() + return row.id + + +# --- authn/authz --------------------------------------------------------------------------------- + + +def test_list_requires_authentication(api_client: FlaskClient) -> None: + response = api_client.get("/api/v1/admin/agent-requests") + + assert response.status_code == 401 + + +def test_approve_requires_authentication(api_client: FlaskClient) -> None: + response = api_client.post(f"/api/v1/admin/agent-requests/{uuid.uuid4()}/approve") + + assert response.status_code == 400 # CSRFProtect rejects an unauthenticated POST first. + + +def test_a_customer_session_gets_403_not_404(api_client: FlaskClient) -> None: + register_response = api_client.post( + "/api/v1/auth/register", + json={"email": "customer@trueup.example", "password": "correct-horse-battery"}, + ) + assert register_response.status_code == 201 + login_response = api_client.post( + "/api/v1/auth/login", + json={"email": "customer@trueup.example", "password": "correct-horse-battery"}, + ) + csrf_token = login_response.get_json()["csrf_token"] + + response = api_client.get( + "/api/v1/admin/agent-requests", headers={"X-CSRFToken": csrf_token} + ) + + assert response.status_code == 403 + + +# --- list/get -------------------------------------------------------------------------------- + + +def test_list_defaults_to_pending_and_is_oldest_first( + api_client: FlaskClient, owner_engine: Engine, staff_member: Staff +) -> None: + csrf_token = _staff_login_with_mfa(api_client) + customer_id = _insert_customer(owner_engine) + first = _insert_request( + owner_engine, + action=AgentActionType.KYC_OVERRIDE, + arguments={"customer_id": str(customer_id), "reason": "first"}, + ) + second = _insert_request( + owner_engine, + action=AgentActionType.KYC_OVERRIDE, + arguments={"customer_id": str(customer_id), "reason": "second"}, + ) + + response = api_client.get( + "/api/v1/admin/agent-requests", headers={"X-CSRFToken": csrf_token} + ) + + assert response.status_code == 200 + body = response.get_json() + ids = [row["id"] for row in body["requests"]] + assert ids == [str(first), str(second)] + + +def test_get_one_returns_404_for_unknown_id( + api_client: FlaskClient, staff_member: Staff +) -> None: + csrf_token = _staff_login_with_mfa(api_client) + + response = api_client.get( + f"/api/v1/admin/agent-requests/{uuid.uuid4()}", headers={"X-CSRFToken": csrf_token} + ) + + assert response.status_code == 404 + + +# --- approve: resolve_break execution mapping --------------------------------------------------- + + +def test_approving_a_resolve_break_request_actually_resolves_the_break( + api_client: FlaskClient, owner_engine: Engine, staff_member: Staff +) -> None: + csrf_token = _staff_login_with_mfa(api_client) + break_id = _insert_break(owner_engine) + request_id = _insert_request( + owner_engine, + action=AgentActionType.RESOLVE_BREAK, + arguments={"break_id": str(break_id), "resolution_note": "confirmed with custodian"}, + ) + + response = api_client.post( + f"/api/v1/admin/agent-requests/{request_id}/approve", + json={"review_note": "approved"}, + headers={"X-CSRFToken": csrf_token}, + ) + + assert response.status_code == 200 + body = response.get_json() + assert body["status"] == "executed" + assert body["executed_at"] is not None + + with Session(bind=owner_engine, expire_on_commit=False) as session: + break_row = session.get(ReconciliationBreak, break_id) + assert break_row is not None + assert break_row.status is ReconciliationBreakStatus.RESOLVED + assert break_row.resolution_note == "confirmed with custodian" + + +def test_approving_a_resolve_break_request_for_an_already_resolved_break_records_execution_failed( + api_client: FlaskClient, owner_engine: Engine, staff_member: Staff +) -> None: + csrf_token = _staff_login_with_mfa(api_client) + break_id = _insert_break(owner_engine) + request_id = _insert_request( + owner_engine, + action=AgentActionType.RESOLVE_BREAK, + arguments={"break_id": str(break_id), "resolution_note": "confirmed"}, + ) + + # Someone else resolves the break out-of-band, between proposal and approval (S13 §6). + with Session(bind=owner_engine, expire_on_commit=False) as session: + break_row = session.get(ReconciliationBreak, break_id) + assert break_row is not None + break_row.status = ReconciliationBreakStatus.RESOLVED + break_row.resolved_by = uuid.uuid4() + break_row.resolved_at = datetime.now(UTC) + session.commit() + + response = api_client.post( + f"/api/v1/admin/agent-requests/{request_id}/approve", + json={"review_note": "approved"}, + headers={"X-CSRFToken": csrf_token}, + ) + + assert response.status_code == 200 + body = response.get_json() + assert body["status"] == "execution_failed" + assert body["execution_error"] is not None + assert body["executed_at"] is None + + +# --- approve: kyc_override execution mapping ----------------------------------------------------- + + +def test_approving_a_kyc_override_request_actually_resets_kyc_status( + api_client: FlaskClient, owner_engine: Engine, staff_member: Staff +) -> None: + csrf_token = _staff_login_with_mfa(api_client) + customer_id = _insert_customer(owner_engine) + request_id = _insert_request( + owner_engine, + action=AgentActionType.KYC_OVERRIDE, + arguments={"customer_id": str(customer_id), "reason": "confirmed manually"}, + ) + + response = api_client.post( + f"/api/v1/admin/agent-requests/{request_id}/approve", + json={}, + headers={"X-CSRFToken": csrf_token}, + ) + + assert response.status_code == 200 + assert response.get_json()["status"] == "executed" + + with Session(bind=owner_engine, expire_on_commit=False) as session: + customer = session.get(Customer, customer_id) + assert customer is not None + assert customer.kyc_status is KycStatus.pending + + +# --- approve: rebalance execution mapping (execution-failure path) -------------------------------- + + +def test_approving_a_rebalance_request_with_no_assigned_model_records_execution_failed( + api_client: FlaskClient, owner_engine: Engine, staff_member: Staff +) -> None: + csrf_token = _staff_login_with_mfa(api_client) + customer_id = _insert_customer(owner_engine) + request_id = _insert_request( + owner_engine, action=AgentActionType.REBALANCE, arguments={"customer_id": str(customer_id)} + ) + + response = api_client.post( + f"/api/v1/admin/agent-requests/{request_id}/approve", + json={}, + headers={"X-CSRFToken": csrf_token}, + ) + + assert response.status_code == 200 + body = response.get_json() + assert body["status"] == "execution_failed" + assert body["execution_error"] is not None + + +# --- approve: transition/validation errors ------------------------------------------------------- + + +def test_approve_returns_404_for_unknown_id(api_client: FlaskClient, staff_member: Staff) -> None: + csrf_token = _staff_login_with_mfa(api_client) + + response = api_client.post( + f"/api/v1/admin/agent-requests/{uuid.uuid4()}/approve", + json={}, + headers={"X-CSRFToken": csrf_token}, + ) + + assert response.status_code == 404 + + +def test_approve_a_non_pending_request_returns_409( + api_client: FlaskClient, owner_engine: Engine, staff_member: Staff +) -> None: + csrf_token = _staff_login_with_mfa(api_client) + customer_id = _insert_customer(owner_engine) + request_id = _insert_request( + owner_engine, + action=AgentActionType.KYC_OVERRIDE, + arguments={"customer_id": str(customer_id), "reason": "x"}, + status=AgentActionStatus.REJECTED, + ) + + response = api_client.post( + f"/api/v1/admin/agent-requests/{request_id}/approve", + json={}, + headers={"X-CSRFToken": csrf_token}, + ) + + assert response.status_code == 409 + + +# --- reject ---------------------------------------------------------------------------------- + + +def test_reject_requires_a_non_empty_review_note( + api_client: FlaskClient, owner_engine: Engine, staff_member: Staff +) -> None: + csrf_token = _staff_login_with_mfa(api_client) + customer_id = _insert_customer(owner_engine) + request_id = _insert_request( + owner_engine, + action=AgentActionType.KYC_OVERRIDE, + arguments={"customer_id": str(customer_id), "reason": "x"}, + ) + + response = api_client.post( + f"/api/v1/admin/agent-requests/{request_id}/reject", + json={}, + headers={"X-CSRFToken": csrf_token}, + ) + + assert response.status_code == 422 + + +def test_reject_never_touches_customer_state( + api_client: FlaskClient, owner_engine: Engine, staff_member: Staff +) -> None: + csrf_token = _staff_login_with_mfa(api_client) + customer_id = _insert_customer(owner_engine) + request_id = _insert_request( + owner_engine, + action=AgentActionType.KYC_OVERRIDE, + arguments={"customer_id": str(customer_id), "reason": "x"}, + ) + + response = api_client.post( + f"/api/v1/admin/agent-requests/{request_id}/reject", + json={"review_note": "not warranted"}, + headers={"X-CSRFToken": csrf_token}, + ) + + assert response.status_code == 200 + assert response.get_json()["status"] == "rejected" + + with Session(bind=owner_engine, expire_on_commit=False) as session: + customer = session.get(Customer, customer_id) + assert customer is not None + assert customer.kyc_status is KycStatus.rejected # unchanged + + +# --- throttling ------------------------------------------------------------------------------- + + +def test_approve_is_throttled( + api_client: FlaskClient, owner_engine: Engine, staff_member: Staff +) -> None: + csrf_token = _staff_login_with_mfa(api_client) + + last_response = None + for _ in range(31): + last_response = api_client.post( + f"/api/v1/admin/agent-requests/{uuid.uuid4()}/approve", + json={}, + headers={"X-CSRFToken": csrf_token}, + ) + + assert last_response is not None + assert last_response.status_code == 429 + assert "Retry-After" in last_response.headers diff --git a/backend/tests/api/test_auth.py b/backend/tests/api/test_auth.py index da842c2..03c72b9 100644 --- a/backend/tests/api/test_auth.py +++ b/backend/tests/api/test_auth.py @@ -1,7 +1,5 @@ -"""`POST /api/v1/auth/*` (S0 §7.1/§7.2) via the Flask test client. - -`register` and `login` are CSRF-exempt (no pre-existing session to protect — S0 §7.1); every route -after that requires the `csrf_token` the preceding step returned, sent as `X-CSRFToken`. +"""`POST /api/v1/auth/*` (S0 §7.1/§7.2) via the Flask test client. `register`/`login` are +CSRF-exempt; every route after requires the `csrf_token` as `X-CSRFToken`. """ from __future__ import annotations @@ -41,8 +39,7 @@ def staff_member(owner_engine: Engine) -> Iterator[Staff]: @pytest.fixture def enrolled_staff_member(owner_engine: Engine) -> Iterator[Staff]: - """A staff member who has already completed MFA enrollment -- `totp_secret_encrypted` is set, - unlike `staff_member` -- for F3's re-enrollment-bypass tests.""" + """A staff member with MFA already enrolled, for F3's re-enrollment-bypass tests.""" from sqlalchemy.orm import Session session = Session(bind=owner_engine, expire_on_commit=False) @@ -166,8 +163,7 @@ def test_login_wrong_password_and_unknown_email_return_the_same_shape( assert wrong_password.status_code == 401 assert unknown_email.status_code == 401 - # Same shape everywhere except the per-request correlation_id: a prober cannot tell "wrong - # password" from "no such account" from the response body (S0 §7 login test list). + # Same shape everywhere except correlation_id (S0 §7 login test list). wrong_password_body = wrong_password.get_json() unknown_email_body = unknown_email.get_json() del wrong_password_body["correlation_id"] @@ -193,8 +189,7 @@ def test_logout_clears_the_session(api_client: FlaskClient) -> None: def test_mfa_enroll_with_no_session_at_all_is_rejected(api_client: FlaskClient) -> None: - """No cookie, no CSRF token — `CSRFProtect`'s `before_request` hook rejects this before the - view's own `UnauthenticatedError` ever runs (still a proper problem+json rejection, S0 §8).""" + """No cookie, no CSRF token — CSRFProtect rejects before the view runs (S0 §8).""" response = api_client.post("/api/v1/auth/mfa/enroll") assert response.status_code == 400 assert response.content_type == "application/problem+json" @@ -203,8 +198,7 @@ def test_mfa_enroll_with_no_session_at_all_is_rejected(api_client: FlaskClient) def test_mfa_enroll_rejects_an_authenticated_customer_with_no_pending_mfa( api_client: FlaskClient, ) -> None: - """A customer's own valid, CSRF-token-bearing session — proving the view's own "only staff, - only with a pending/authenticated staff session" check (not just CSRF) gates this route.""" + """A valid customer session must still be rejected: this route is staff-only.""" assert _register(api_client).status_code == 201 login_response = _login(api_client, email=CUSTOMER_EMAIL, password=CUSTOMER_PASSWORD) csrf_token = login_response.get_json()["csrf_token"] @@ -250,9 +244,7 @@ def test_full_staff_mfa_enrollment_and_verification_flow( def test_mfa_enroll_rejects_re_enrollment_via_a_pending_session_when_already_enrolled( api_client: FlaskClient, enrolled_staff_member: Staff ) -> None: - """A correct password alone (the `pending_mfa_user_id` state `/login` sets) must not be - enough to replace an existing MFA secret -- otherwise the second factor adds no assurance - beyond the password it exists to supplement.""" + """A correct password alone must not be enough to replace an existing MFA secret.""" login_response = _login(api_client, email=STAFF_EMAIL, password=STAFF_PASSWORD) assert login_response.status_code == 200 assert login_response.get_json()["status"] == "mfa_required" @@ -267,8 +259,8 @@ def test_mfa_enroll_rejects_re_enrollment_via_a_pending_session_when_already_enr def test_mfa_enroll_reset_requires_password_reentry( api_client: FlaskClient, enrolled_staff_member: Staff ) -> None: - """An already-fully-authenticated staff session (post-MFA) must still re-prove the password - before replacing an existing secret -- a hijacked session alone is not enough.""" + """A fully-authenticated staff session must still re-prove the password to replace the + secret.""" login_response = _login(api_client, email=STAFF_EMAIL, password=STAFF_PASSWORD) csrf_token = login_response.get_json()["csrf_token"] code = pyotp.TOTP(enrolled_staff_member.totp_secret_encrypted).now() diff --git a/backend/tests/api/test_chat.py b/backend/tests/api/test_chat.py index 4416927..92ea536 100644 --- a/backend/tests/api/test_chat.py +++ b/backend/tests/api/test_chat.py @@ -9,7 +9,7 @@ from typing import TYPE_CHECKING import pytest -from sqlalchemy import select +from sqlalchemy import select, text import app.controllers.api.chat as chat_controller from app.integrations.openai.fake_agent_adapter import FakeAgentAdapter @@ -37,8 +37,9 @@ def _chat_tables(owner_engine: Engine) -> Iterator[None]: for table in _TABLES: table.create(bind=owner_engine, checkfirst=True) yield None - for table in reversed(_TABLES): - table.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + for table in reversed(_TABLES): + connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) @pytest.fixture(autouse=True) @@ -81,8 +82,7 @@ def _read_sse_events(raw_text: str) -> list[dict[str, object]]: def test_list_sessions_requires_authentication(api_client: FlaskClient) -> None: - """`GET` is CSRF-exempt by `CSRFProtect`'s own default (unlike the `POST` routes below), so - this is the route that isolates the authentication check itself.""" + """GET is CSRF-exempt, so this isolates the authentication check itself.""" response = api_client.get("/api/v1/chat/sessions") assert response.status_code == 401 diff --git a/backend/tests/api/test_error_contract.py b/backend/tests/api/test_error_contract.py index ee74ea3..21e8471 100644 --- a/backend/tests/api/test_error_contract.py +++ b/backend/tests/api/test_error_contract.py @@ -1,8 +1,5 @@ -"""The app factory renders `AppError` as RFC 9457 problem+json (S0 §8). - -`app/core/errors.py` owns the hierarchy and knows nothing about Flask. This module is the seam: -it proves the factory actually installs a handler for it, that the stable `code` survives to the -client, and that a `detail` carried for logging never crosses the boundary. +"""The app factory renders `AppError` as RFC 9457 problem+json (S0 §8): stable `code` survives to +the client, `detail` never does. """ from __future__ import annotations @@ -59,8 +56,8 @@ def test_app_errors_render_as_problem_json( def test_detail_never_reaches_the_client(raising_client: FlaskClient) -> None: - """A forbidden error names both customer IDs for the audit log. Neither may be returned — - echoing them back confirms to an attacker that a probed identifier exists (OWASP API1).""" + """Neither customer ID may be echoed back — that would confirm a probed identifier exists + (OWASP API1).""" rendered = raising_client.get("/_test/forbidden").get_data(as_text=True) assert "8f3a" not in rendered assert "91bc" not in rendered diff --git a/backend/tests/api/test_fees.py b/backend/tests/api/test_fees.py index a4aefc7..32cb319 100644 --- a/backend/tests/api/test_fees.py +++ b/backend/tests/api/test_fees.py @@ -1,6 +1,5 @@ """`GET /api/v1/fees`, `POST /api/v1/payment-methods` (S10 §7) via the Flask test client: happy -path, authn/ownership, and throttling -- matching `test_funding.py`/`test_identity.py`'s exact -conventions (CSRF header, `_register_and_login`, `_reset_rate_limits`). +path, authn/ownership, and throttling. """ from __future__ import annotations @@ -115,13 +114,7 @@ def test_get_fees_is_throttled(api_client: FlaskClient) -> None: def test_attach_payment_method_requires_authentication(api_client: FlaskClient) -> None: - """`CSRFProtect` runs before any view-level `@login_required` check on every `POST` route in - this app (see `app/controllers/api/auth.py`'s own note on this ordering) -- a request with no - session also has no CSRF token, so it is rejected at 400, never reaching the auth check. This - matches every other POST endpoint in this codebase: none of them assert 401 for an - unauthenticated POST, precisely because CSRF tokens are only ever issued at login/mfa-verify/ - session-restore (root CLAUDE.md's wire-format contract), so there is no way to send a - CSRF-valid, session-less request to isolate the authentication check alone.""" + """CSRFProtect rejects an unauthenticated POST at 400, before the auth check ever runs.""" response = api_client.post( "/api/v1/payment-methods", json={"customer_id": str(uuid.uuid4()), "payment_method_id": "pm_card_visa"}, diff --git a/backend/tests/api/test_funding.py b/backend/tests/api/test_funding.py index bcd88df..dfe9fe0 100644 --- a/backend/tests/api/test_funding.py +++ b/backend/tests/api/test_funding.py @@ -9,7 +9,7 @@ import pytest from flask.testing import FlaskClient -from sqlalchemy import Engine, select +from sqlalchemy import Engine, select, text from app.integrations.fake.fake_bank import FakeBankAdapter from app.models.identity.bank_link import BankLink @@ -37,9 +37,7 @@ SettlementObligation.__table__, CustomerCashLock.__table__, IdempotencyKey.__table__, - # A withdrawal now checks real order holds/open buy commitments (OrderHoldsProvider, wired in - # place of the NullHoldsProvider stand-in) -- these tables must exist for that query to run, - # even when a given test never places an order. + # Withdrawal checks real order holds (OrderHoldsProvider); these tables must exist. Order.__table__, ApprovalHold.__table__, ] @@ -50,8 +48,9 @@ def _funding_tables(owner_engine: Engine) -> Iterator[None]: for table in _TABLES: table.create(bind=owner_engine, checkfirst=True) yield None - for table in reversed(_TABLES): - table.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + for table in reversed(_TABLES): + connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) @pytest.fixture(autouse=True) diff --git a/backend/tests/api/test_identity.py b/backend/tests/api/test_identity.py index cd64d2b..0032f5d 100644 --- a/backend/tests/api/test_identity.py +++ b/backend/tests/api/test_identity.py @@ -9,7 +9,7 @@ import pytest from flask.testing import FlaskClient -from sqlalchemy import Engine +from sqlalchemy import Engine, text from sqlalchemy.orm import Session from werkzeug.test import TestResponse @@ -17,17 +17,27 @@ from app.integrations.fake.fake_kyc import FakeKycAdapter from app.models.identity.customer import Customer, KycStatus from app.models.identity.kyc_session import KycSession +from app.models.ledger.account import Account +from app.models.ledger.customer_cash_lock import CustomerCashLock CUSTOMER_EMAIL = "identity-customer@trueup.example" CUSTOMER_PASSWORD = "correct-horse-battery" OTHER_EMAIL = "identity-other@trueup.example" +# `Account`/`CustomerCashLock` are needed only once a verdict reaches AccountApprovalService's +# ledger-provisioning step (the self-heal tests below); listed alongside `KycSession` so every +# test in this file shares one table lifecycle, matching `test_funding.py`'s convention. +_TABLES = [KycSession.__table__, Account.__table__, CustomerCashLock.__table__] + @pytest.fixture(autouse=True) def _kyc_session_table(owner_engine: Engine) -> Iterator[None]: - KycSession.__table__.create(bind=owner_engine, checkfirst=True) + for table in _TABLES: + table.create(bind=owner_engine, checkfirst=True) yield None - KycSession.__table__.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + for table in reversed(_TABLES): + connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) @pytest.fixture(autouse=True) @@ -109,10 +119,8 @@ def test_start_kyc_session_rejects_another_customers_id(api_client: FlaskClient) def test_start_kyc_session_is_blocked_once_locked_rejected( api_client: FlaskClient, owner_engine: Engine ) -> None: - """S2 §9/S8 §6 case 3: exhausted attempts lock `kyc_status` to `rejected`, and a further - `POST /identity/kyc-sessions` is rejected with a clear error rather than opening another - attempt -- only the adviser override (`POST /admin/kyc-overrides/`) can reopen - it.""" + """S2 §9/S8 §6 case 3: exhausted attempts lock kyc_status to rejected; only an adviser + override can reopen.""" customer_id, csrf_token = _register_and_login(api_client) first = _start_kyc_session(api_client, customer_id=customer_id, csrf_token=csrf_token) assert first.status_code == 201 @@ -180,3 +188,54 @@ def test_get_identity_status_rejects_another_customers_id(api_client: FlaskClien response = api_client.get(f"/api/v1/identity/status/{other_id}") assert response.status_code == 403 + + +def test_get_identity_status_self_heals_when_the_verdict_webhook_never_arrives( + api_client: FlaskClient, monkeypatch: pytest.MonkeyPatch +) -> None: + """The exact local-dev scenario this exists for: Stripe can't reach `localhost` to deliver + `identity.verification_session.verified`, so no webhook ever lands -- the status endpoint must + still resolve by asking the provider directly, with no webhook involved at all.""" + import app.controllers.api.identity as identity_controller + + shared_port = FakeKycAdapter() + monkeypatch.setattr(identity_controller, "_build_kyc_port", lambda: shared_port) + + customer_id, csrf_token = _register_and_login(api_client) + started = _start_kyc_session(api_client, customer_id=customer_id, csrf_token=csrf_token) + assert started.status_code == 201 + provider_session_id = started.get_json()["provider_session_id"] + + pending_response = api_client.get(f"/api/v1/identity/status/{customer_id}") + assert pending_response.get_json()["kyc_status"] == "pending" + + shared_port.retrieved_statuses[provider_session_id] = "verified" + + response = api_client.get(f"/api/v1/identity/status/{customer_id}") + + assert response.status_code == 200 + assert response.get_json()["kyc_status"] == "approved" + + +def test_get_identity_status_does_not_repoll_once_already_resolved( + api_client: FlaskClient, monkeypatch: pytest.MonkeyPatch +) -> None: + import app.controllers.api.identity as identity_controller + + shared_port = FakeKycAdapter() + monkeypatch.setattr(identity_controller, "_build_kyc_port", lambda: shared_port) + + customer_id, csrf_token = _register_and_login(api_client) + started = _start_kyc_session(api_client, customer_id=customer_id, csrf_token=csrf_token) + provider_session_id = started.get_json()["provider_session_id"] + shared_port.retrieved_statuses[provider_session_id] = "verified" + first = api_client.get(f"/api/v1/identity/status/{customer_id}") + assert first.get_json()["kyc_status"] == "approved" + + # If this second call polled the provider again, a "canceled" status would flip the customer + # to rejected -- it must not, since kyc_session already transitioned exactly once. + shared_port.retrieved_statuses[provider_session_id] = "canceled" + + response = api_client.get(f"/api/v1/identity/status/{customer_id}") + + assert response.get_json()["kyc_status"] == "approved" diff --git a/backend/tests/api/test_lots.py b/backend/tests/api/test_lots.py index 7143451..6f1804d 100644 --- a/backend/tests/api/test_lots.py +++ b/backend/tests/api/test_lots.py @@ -1,6 +1,5 @@ -"""`GET /api/v1/lots` (S8 §3, data owned by S5) via the Flask test client: happy path (including -the wash-sale-adjusted figure and a provisional consumption's flag), authn/ownership, and -throttling -- matching `test_fees.py`/`test_admin_rebalance_api.py`'s exact conventions. +"""`GET /api/v1/lots` (S8 §3, data owned by S5) via the Flask test client: happy path, wash-sale +adjustment, authn/ownership, and throttling. """ from __future__ import annotations @@ -119,9 +118,8 @@ def _seed_fill_order_event( def _seed_lot_with_wash_sale_and_provisional_sale( owner_engine: Engine, customer_id: uuid.UUID ) -> tuple[uuid.UUID, str]: - """One lot whose `adjusted_basis` has already absorbed a wash-sale-disallowed loss (S5 §5) - and carries one still-provisional sell consumption (S5 §3.2) -- the two figures `GET - /api/v1/lots` must never conflate with their pre-adjustment/locked counterparts.""" + """A lot with an already-adjusted basis (wash sale, S5 §5) and a provisional consumption + (S5 §3.2).""" session = Session(bind=owner_engine, expire_on_commit=False) try: security = Security( diff --git a/backend/tests/api/test_orders.py b/backend/tests/api/test_orders.py index a691d1b..c3b9963 100644 --- a/backend/tests/api/test_orders.py +++ b/backend/tests/api/test_orders.py @@ -33,9 +33,7 @@ CUSTOMER_EMAIL = "order-customer@trueup.example" CUSTOMER_PASSWORD = "correct-horse-battery" -# `OrderService.enqueue_submission`/the controller's `_to_order_response` both resolve `symbol` -# from the real securities catalogue now (S5) -- every test payload's `security_id` must name a -# real row, seeded once here rather than a fresh `uuid.uuid4()` per call. +# `security_id` must name a real securities-catalogue row (S5); seeded once here. SECURITY_ID = uuid.uuid4() SECURITY_SYMBOL = "AAPL" DEFAULT_TEST_CASH = Money("1000000.00") @@ -71,8 +69,9 @@ def _order_tables(owner_engine: Engine) -> Iterator[None]: session.commit() session.close() yield None - for table in reversed(tables): - table.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + for table in reversed(tables): + connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) @pytest.fixture(autouse=True) @@ -89,9 +88,8 @@ def _clean_order_tables(owner_engine: Engine, _order_tables: None) -> Iterator[N class _LedgerLikeUow: - """Duck-typed stand-in for `LedgerUnitOfWork`, matching `test_cash_policy.py`'s own fixture - helper -- fixture setup, not the thing under test, so `PostingService`'s own contract is - enough without a real `OrdersUnitOfWork`.""" + """Duck-typed stand-in for `LedgerUnitOfWork`, matching `test_cash_policy.py`'s fixture + helper.""" def __init__(self, session: Session) -> None: self.session = session @@ -114,11 +112,8 @@ def _register_and_approve_customer( email: str = CUSTOMER_EMAIL, cash: Money = DEFAULT_TEST_CASH, ) -> uuid.UUID: - """Registers via the real endpoint, then directly grants KYC/account approval, creates the - cash-lock row, and (unless `cash=Money("0.00")`) posts a settled deposit large enough that the - F1 investable-cash check (`OrderService.create_order`) never blocks an ordinary test order -- - standing in for `AccountApprovalService`/`DepositService`'s jobs (S2), which this sub-project - does not own and should not re-invoke end to end just to set up a fixture.""" + """Registers, grants KYC/account approval, and posts a settled deposit so the F1 + investable-cash check passes.""" response = client.post( "/api/v1/auth/register", json={"email": email, "password": CUSTOMER_PASSWORD} ) @@ -226,8 +221,7 @@ def test_create_order_above_threshold_requires_approval( assert response.get_json()["status"] == "awaiting_approval" -# --- create: cash policy (S0 §10.1; the buy path must check investable cash, not just write the -# hold -- a customer with no settled or unsettled inflow can otherwise place an unbounded buy) -- +# --- create: cash policy (S0 §10.1) --------------------------------------------------------- def test_create_order_rejects_a_buy_exceeding_investable_cash( diff --git a/backend/tests/api/test_portfolios_api.py b/backend/tests/api/test_portfolios_api.py index fb820c3..e6d3288 100644 --- a/backend/tests/api/test_portfolios_api.py +++ b/backend/tests/api/test_portfolios_api.py @@ -1,6 +1,5 @@ -"""`GET /api/v1/portfolios/models`, `GET, POST /api/v1/portfolios/assignment` (S8 §3, "Owning -spec: S9 §3") via the Flask test client: happy path, validation errors, authn/authz/ownership, and -throttling. +"""`GET /api/v1/portfolios/models`, `GET, POST /api/v1/portfolios/assignment` (S8 §3, S9 §3) via +the Flask test client. """ from __future__ import annotations diff --git a/backend/tests/api/test_staff_api_tokens.py b/backend/tests/api/test_staff_api_tokens.py new file mode 100644 index 0000000..243769e --- /dev/null +++ b/backend/tests/api/test_staff_api_tokens.py @@ -0,0 +1,190 @@ +"""`app/controllers/admin/staff_api_tokens.py` (S13 §3.2) via the Flask test client: issue/list/ +revoke, self-service enforcement, validation, authn/authz, and throttling. +""" + +from __future__ import annotations + +import uuid +from collections.abc import Iterator + +import pyotp +import pytest +from flask.testing import FlaskClient +from sqlalchemy import Engine, text +from sqlalchemy.orm import Session + +from app.models.identity.staff import Staff, StaffRole +from app.models.identity.staff_api_token import StaffApiToken +from app.models.ops.admin_audit_log import AdminAuditLog +from app.services.identity.auth import hash_password + +STAFF_EMAIL = "token-adviser@trueup.example" +STAFF_PASSWORD = "another-strong-password" +OTHER_STAFF_EMAIL = "token-other-adviser@trueup.example" + +# Staff/Customer are owned by tests/api/conftest.py's session-scoped fixture, not here. +_TABLES = [StaffApiToken.__table__, AdminAuditLog.__table__] + + +@pytest.fixture(autouse=True) +def _tables(owner_engine: Engine) -> Iterator[None]: + for table in _TABLES: + table.create(bind=owner_engine, checkfirst=True) + yield None + with owner_engine.begin() as connection: + for table in reversed(_TABLES): + connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) + + +@pytest.fixture +def staff_member(owner_engine: Engine) -> Iterator[Staff]: + session = Session(bind=owner_engine, expire_on_commit=False) + staff = Staff( + email=STAFF_EMAIL, password_hash=hash_password(STAFF_PASSWORD), role=StaffRole.adviser + ) + session.add(staff) + session.commit() + yield staff + session.close() + + +@pytest.fixture +def other_staff_member(owner_engine: Engine) -> Iterator[Staff]: + session = Session(bind=owner_engine, expire_on_commit=False) + staff = Staff( + email=OTHER_STAFF_EMAIL, + password_hash=hash_password("irrelevant-password"), + role=StaffRole.adviser, + ) + session.add(staff) + session.commit() + yield staff + session.close() + + +def _staff_login_with_mfa( + client: FlaskClient, *, email: str = STAFF_EMAIL, password: str = STAFF_PASSWORD +) -> str: + login_response = client.post( + "/api/v1/auth/login", json={"email": email, "password": password} + ) + assert login_response.status_code == 200 + pending_csrf = login_response.get_json()["csrf_token"] + secret = client.post( + "/api/v1/auth/mfa/enroll", headers={"X-CSRFToken": pending_csrf} + ).get_json()["secret"] + code = pyotp.TOTP(secret).now() + verify = client.post( + "/api/v1/auth/mfa/verify", json={"code": code}, headers={"X-CSRFToken": pending_csrf} + ) + assert verify.status_code == 200 + csrf_token: str = verify.get_json()["csrf_token"] + return csrf_token + + +def test_requires_authentication(api_client: FlaskClient) -> None: + response = api_client.get("/api/v1/admin/staff-api-tokens") + + assert response.status_code == 401 + + +def test_issue_requires_a_non_empty_label(api_client: FlaskClient, staff_member: Staff) -> None: + csrf_token = _staff_login_with_mfa(api_client) + + response = api_client.post( + "/api/v1/admin/staff-api-tokens", json={}, headers={"X-CSRFToken": csrf_token} + ) + + assert response.status_code == 422 + + +def test_issue_returns_the_raw_token_exactly_once( + api_client: FlaskClient, staff_member: Staff +) -> None: + csrf_token = _staff_login_with_mfa(api_client) + + response = api_client.post( + "/api/v1/admin/staff-api-tokens", + json={"label": "ops laptop MCP client"}, + headers={"X-CSRFToken": csrf_token}, + ) + + assert response.status_code == 201 + body = response.get_json() + assert body["label"] == "ops laptop MCP client" + assert len(body["token"]) > 20 + + list_response = api_client.get( + "/api/v1/admin/staff-api-tokens", headers={"X-CSRFToken": csrf_token} + ) + assert list_response.status_code == 200 + tokens = list_response.get_json()["tokens"] + assert len(tokens) == 1 + assert "token" not in tokens[0] + assert "token_hash" not in tokens[0] + + +def test_revoke_marks_the_token_revoked(api_client: FlaskClient, staff_member: Staff) -> None: + csrf_token = _staff_login_with_mfa(api_client) + issued = api_client.post( + "/api/v1/admin/staff-api-tokens", + json={"label": "a token"}, + headers={"X-CSRFToken": csrf_token}, + ).get_json() + + response = api_client.delete( + f"/api/v1/admin/staff-api-tokens/{issued['id']}", headers={"X-CSRFToken": csrf_token} + ) + + assert response.status_code == 200 + assert response.get_json()["revoked_at"] is not None + + +def test_revoking_an_unknown_token_returns_404( + api_client: FlaskClient, staff_member: Staff +) -> None: + csrf_token = _staff_login_with_mfa(api_client) + + response = api_client.delete( + f"/api/v1/admin/staff-api-tokens/{uuid.uuid4()}", headers={"X-CSRFToken": csrf_token} + ) + + assert response.status_code == 404 + + +def test_cannot_revoke_another_staff_members_token( + api_client: FlaskClient, staff_member: Staff, other_staff_member: Staff +) -> None: + csrf_token = _staff_login_with_mfa(api_client) + issued = api_client.post( + "/api/v1/admin/staff-api-tokens", + json={"label": "adviser's own token"}, + headers={"X-CSRFToken": csrf_token}, + ).get_json() + api_client.post("/api/v1/auth/logout", headers={"X-CSRFToken": csrf_token}) + + other_csrf_token = _staff_login_with_mfa( + api_client, email=OTHER_STAFF_EMAIL, password="irrelevant-password" + ) + + response = api_client.delete( + f"/api/v1/admin/staff-api-tokens/{issued['id']}", headers={"X-CSRFToken": other_csrf_token} + ) + + assert response.status_code == 403 + + +def test_issue_is_throttled(api_client: FlaskClient, staff_member: Staff) -> None: + csrf_token = _staff_login_with_mfa(api_client) + + last_response = None + for _ in range(11): + last_response = api_client.post( + "/api/v1/admin/staff-api-tokens", + json={"label": "spam"}, + headers={"X-CSRFToken": csrf_token}, + ) + + assert last_response is not None + assert last_response.status_code == 429 + assert "Retry-After" in last_response.headers diff --git a/backend/tests/api/test_statements_export.py b/backend/tests/api/test_statements_export.py index 6e9c613..f7188e3 100644 --- a/backend/tests/api/test_statements_export.py +++ b/backend/tests/api/test_statements_export.py @@ -1,6 +1,5 @@ -"""`GET /api/v1/statements//export` (S8 §5, FR-36) via the Flask test client: the CSV -export happy path (wash-sale-adjusted figures, a provisional row included), the "not yet -published" edge case (S8 §6 case 1), authn/ownership, and throttling. +"""`GET /api/v1/statements//export` (S8 §5, FR-36) via the Flask test client: CSV export, +the not-yet-published edge case, authn/ownership, and throttling. """ from __future__ import annotations diff --git a/backend/tests/api/test_valuation_api.py b/backend/tests/api/test_valuation_api.py index c66eaef..69bf802 100644 --- a/backend/tests/api/test_valuation_api.py +++ b/backend/tests/api/test_valuation_api.py @@ -1,8 +1,5 @@ -"""`GET /api/v1/valuation/*` (S4 §7) via the Flask test client. - -S4 §9 calls out a `views/` contract test proving `completeness`/`is_provisional` survive from the -service layer into the response body -- this file is that test, exercised through the real HTTP -surface rather than at the schema level alone. +"""`GET /api/v1/valuation/*` (S4 §7) via the Flask test client: `completeness`/`is_provisional` +survive from the service layer into the response body (S4 §9). """ from __future__ import annotations @@ -55,17 +52,8 @@ @pytest.fixture(autouse=True) def _valuation_tables(owner_engine: Engine) -> Iterator[None]: - """Function-scoped create-before/drop-after, matching every other test file's convention - (`tests/integration/conftest.py`'s `ledger_tables`) -- deliberately not a session-scoped - truncate-between-tests fixture, since these tables (`inbound_event`, `account`, ...) are also - populated by other sub-projects' own fixtures, and a CASCADE truncate/drop reaching across a - shared FK graph mid-session risks wiping rows another file's test still depends on. - - Teardown uses raw `DROP TABLE ... IF EXISTS`, not `Table.drop()`: `market_data_source` is one - Postgres enum shared by two tables (`daily_close`, `market_calendar_cache`), and SQLAlchemy's - per-Table drop event tries to drop the enum type alongside whichever of the two tables is - dropped first, failing with `DependentObjectsStillExist` while the other table still - references it (matches `tests/integration/test_valuation_service.py`'s `valuation_tables`).""" + """Function-scoped create-before/drop-after. Raw DROP TABLE (not Table.drop()) avoids a + DependentObjectsStillExist race over the shared market_data_source enum type.""" for table in VALUATION_TABLES: table.create(bind=owner_engine, checkfirst=True) yield None @@ -197,14 +185,8 @@ def test_balance_is_throttled(api_client: FlaskClient) -> None: @pytest.mark.xfail( - reason=( - "Blocked on a foundation bug (escalated to main, not S4's to fix): " - "app/controllers/api/auth.py's load_user() returns its principal from inside a " - "never-committed UnitOfWork, so UnitOfWork.__exit__ rolls back (expiring every mapped " - "attribute) before closing (detaching it). Staff.role is a real mapped column, so " - "app/core/security.py's requires_role() raises DetachedInstanceError on " - "`current_user.role` for every staff session on every request after login." - ), + reason="Blocked on a foundation bug (escalated to main): staff sessions raise " + "DetachedInstanceError on requires_role() after login.", strict=False, ) def test_balance_for_staff_without_customer_id_is_a_validation_error( @@ -231,10 +213,8 @@ def test_balance_for_staff_without_customer_id_is_a_validation_error( @pytest.mark.xfail( - reason=( - "Blocked on the same foundation bug as " - "test_balance_for_staff_without_customer_id_is_a_validation_error -- see its reason." - ), + reason="Same foundation bug as " + "test_balance_for_staff_without_customer_id_is_a_validation_error.", strict=False, ) def test_balance_for_staff_with_customer_id_sees_that_customers_balance( diff --git a/backend/tests/api/test_webhooks_stripe.py b/backend/tests/api/test_webhooks_stripe.py index 6e53b52..13bf275 100644 --- a/backend/tests/api/test_webhooks_stripe.py +++ b/backend/tests/api/test_webhooks_stripe.py @@ -1,13 +1,5 @@ -"""`POST /webhooks/stripe_identity`, `POST /webhooks/stripe_billing` (S2 §6, S10 §7, ADR 9/10) via -the Flask test client -- signature verification and, specifically, the F4 fix: dedup must key on -the Stripe *event* id, never the verification-session/PaymentIntent id, or every event after the -first for one object is silently dropped as a false duplicate (a real, previously-shipped bug). - -No test anywhere in this codebase hit a `/webhooks/*` URL before this file (found during a full -security audit) -- these endpoints are unauthenticated by design (external callers) and carry the -CSRF exemption and lack of throttling that goes with that, so signature verification is the entire -security perimeter, and is worth testing directly rather than only through unit tests of the -verifier class in isolation. +"""Stripe webhook endpoints via the Flask test client (S2 §6, S10 §7, ADR 9/10): signature +verification and the F4 dedup-on-event-id fix. """ from __future__ import annotations @@ -35,22 +27,14 @@ @pytest.fixture(autouse=True) def _webhook_settings(monkeypatch: pytest.MonkeyPatch) -> None: - # `conftest.py`'s autouse `_default_settings_env` fixture already makes `get_settings()` - # constructible without a `.env` (every other required field); this fixture only adds the two - # webhook secrets that fixture has no reason to know about. + # Adds the two webhook secrets `conftest.py`'s default settings fixture doesn't cover. settings = get_settings() monkeypatch.setattr(settings, "stripe_webhook_secret_identity", SecretStr(IDENTITY_SECRET)) monkeypatch.setattr(settings, "stripe_webhook_secret_billing", SecretStr(BILLING_SECRET)) _WEBHOOK_TABLES = [ - # `Customer` is deliberately excluded: `tests/api/conftest.py` already owns its lifecycle at - # session scope. Every table below is *also* independently managed by other test files' - # session-scoped fixtures (test_orders.py, test_fees.py, ...) -- function-scoped - # create/`DROP ... CASCADE` per test (test_fees.py's own proven pattern) avoids the - # teardown-ordering conflict a second session-scoped owner of the same table names would - # cause (confirmed: an earlier session-scoped version of this fixture broke 41 unrelated - # tests elsewhere in the suite via out-of-order `DependentObjectsStillExist` at session end). + # Customer is excluded: conftest.py owns its lifecycle at session scope. InboundEvent.__table__, JournalEntry.__table__, KycSession.__table__, @@ -148,9 +132,7 @@ def test_stripe_identity_webhook_accepts_a_validly_signed_event( def test_stripe_identity_webhook_processes_two_different_events_for_the_same_session( api_client: FlaskClient, owner_engine: Engine ) -> None: - """F4: `requires_input` then `verified` for the *same* verification session are two distinct - Stripe events (different `id`s) sharing one session id. Before the fix, the second was - silently dropped as a duplicate of the first because dedup keyed on the shared session id.""" + """F4: two distinct events sharing one session id must both persist.""" first = _identity_event(event_id="evt_1", session_id="vs_shared", status="requires_input") second = _identity_event(event_id="evt_2", session_id="vs_shared", status="verified") @@ -173,16 +155,13 @@ def test_stripe_identity_webhook_processes_two_different_events_for_the_same_ses assert first_response.status_code == 200 assert second_response.status_code == 200 - # Both persisted as distinct inbound events -- neither treated as a duplicate of the other. - assert _inbound_event_count(owner_engine) == 2 + assert _inbound_event_count(owner_engine) == 2 # both persisted, neither a duplicate def test_stripe_identity_webhook_still_dedupes_a_genuine_redelivery( api_client: FlaskClient, owner_engine: Engine ) -> None: - """The exact same event id delivered twice (Stripe's own documented at-least-once redelivery) - must still collapse to exactly one recorded event -- the fix must not turn dedup off, only - key it correctly.""" + """The same event id delivered twice must still collapse to one recorded event.""" body = _identity_event(event_id="evt_redelivered", session_id="vs_1", status="verified") signature = _sign(body, secret=IDENTITY_SECRET) @@ -226,9 +205,7 @@ def test_stripe_billing_webhook_rejects_an_invalid_signature(api_client: FlaskCl def test_stripe_billing_webhook_processes_two_different_events_for_the_same_payment_intent( api_client: FlaskClient, owner_engine: Engine ) -> None: - """F4: `processing` then `succeeded` for the *same* PaymentIntent are two distinct Stripe - events sharing one PaymentIntent id. Before the fix, the second was silently dropped as a - duplicate, so a fee_charge was never marked paid.""" + """F4: two distinct events sharing one PaymentIntent id must both persist.""" first = _billing_event(event_id="evt_1", payment_intent_id="pi_shared", status="processing") second = _billing_event(event_id="evt_2", payment_intent_id="pi_shared", status="succeeded") @@ -251,7 +228,7 @@ def test_stripe_billing_webhook_processes_two_different_events_for_the_same_paym assert first_response.status_code == 200 assert second_response.status_code == 200 - assert _inbound_event_count(owner_engine) == 2 + assert _inbound_event_count(owner_engine) == 2 # both persisted, neither a duplicate def test_stripe_billing_webhook_still_dedupes_a_genuine_redelivery( diff --git a/backend/tests/contract/test_bank_port.py b/backend/tests/contract/test_bank_port.py index f5b304e..effc96c 100644 --- a/backend/tests/contract/test_bank_port.py +++ b/backend/tests/contract/test_bank_port.py @@ -1,6 +1,5 @@ -"""`BankPort` contract (S2 §8): the same assertions against `FakeBankAdapter` and, when Plaid -sandbox credentials plus a real sandbox public token are configured, `PlaidBankAdapter` -- so the -fake cannot silently drift from the real provider it stands in for (`backend/CLAUDE.md`). +"""`BankPort` contract (S2 §8): identical assertions against `FakeBankAdapter` and, when +configured, the real `PlaidBankAdapter`. """ from __future__ import annotations diff --git a/backend/tests/contract/test_broker_port.py b/backend/tests/contract/test_broker_port.py index 01e9930..b9d7555 100644 --- a/backend/tests/contract/test_broker_port.py +++ b/backend/tests/contract/test_broker_port.py @@ -1,6 +1,5 @@ -"""`BrokerPort` contract (S3 §8): the same assertions against `FakeBrokerAdapter` and, when Alpaca -paper-trading credentials are configured, `AlpacaBrokerAdapter` -- so the fake cannot silently -drift from the provider it stands in for (`backend/CLAUDE.md`). +"""`BrokerPort` contract (S3 §8): identical assertions against `FakeBrokerAdapter` and, when +configured, the real `AlpacaBrokerAdapter`. """ from __future__ import annotations diff --git a/backend/tests/contract/test_kyc_port.py b/backend/tests/contract/test_kyc_port.py index 8ea51a6..fa71a82 100644 --- a/backend/tests/contract/test_kyc_port.py +++ b/backend/tests/contract/test_kyc_port.py @@ -1,6 +1,5 @@ -"""`KycPort` contract (S2 §8): the same assertions against `FakeKycAdapter` and, when Stripe test -credentials are configured, `StripeKycAdapter` -- so the fake cannot silently drift from the real -provider it stands in for (`backend/CLAUDE.md`). +"""`KycPort` contract (S2 §8): identical assertions against `FakeKycAdapter` and, when configured, +the real `StripeKycAdapter`. """ from __future__ import annotations @@ -13,14 +12,22 @@ from app.integrations.ports import KycPort -def _assert_valid_handle(port: KycPort) -> None: +def _assert_valid_handle(port: KycPort) -> str: handle = port.create_verification_session(customer_id="00000000-0000-0000-0000-000000000001") assert handle.provider_session_id assert handle.client_secret + return handle.provider_session_id + + +def _assert_retrieves_a_status(port: KycPort, provider_session_id: str) -> None: + status = port.retrieve_verification_session(provider_session_id=provider_session_id) + assert isinstance(status, str) + assert status def test_fake_kyc_adapter_satisfies_the_contract() -> None: - _assert_valid_handle(FakeKycAdapter()) + provider_session_id = _assert_valid_handle(FakeKycAdapter()) + _assert_retrieves_a_status(FakeKycAdapter(), provider_session_id) @pytest.mark.requires_credentials @@ -31,4 +38,6 @@ def test_fake_kyc_adapter_satisfies_the_contract() -> None: def test_real_stripe_kyc_adapter_satisfies_the_contract() -> None: from app.integrations.stripe.kyc_adapter import StripeKycAdapter - _assert_valid_handle(StripeKycAdapter(api_key=os.environ["STRIPE_SECRET_KEY"])) + adapter = StripeKycAdapter(api_key=os.environ["STRIPE_SECRET_KEY"]) + provider_session_id = _assert_valid_handle(adapter) + _assert_retrieves_a_status(adapter, provider_session_id) diff --git a/backend/tests/contract/test_llm_agent_port.py b/backend/tests/contract/test_llm_agent_port.py index a1f4daa..6dea272 100644 --- a/backend/tests/contract/test_llm_agent_port.py +++ b/backend/tests/contract/test_llm_agent_port.py @@ -1,14 +1,5 @@ -"""`LlmAgentPort` contract (S11 §7.4, ADR 18): the same assertions against `FakeAgentAdapter` and, -when an `OPENAI_API_KEY` is configured, `OpenAIAgentAdapter` -- so the fake cannot silently drift -from the real provider it stands in for (`backend/CLAUDE.md`). - -The dedicated adversarial-injection fixture (`test_adversarial_tool_result_is_never_...`) feeds a -tool result containing text that reads like an instruction through the port and asserts the -adapter does not treat it as a command to escalate scope -- proving the *port's own contract* -(tool results are opaque data, never re-parsed as commands). This is a quality/contract property, -not the security boundary: ADR 19's boundary is the database role and validator -(`tests/integration/test_chat_security_perimeter.py`), which holds regardless of what any model -or adapter does. +"""`LlmAgentPort` contract (S11 §7.4, ADR 18): identical assertions against `FakeAgentAdapter` and, +when configured, the real `OpenAIAgentAdapter`. """ from __future__ import annotations @@ -33,8 +24,7 @@ class _RecordingContext: - """Test double tracking every call `LlmAgentPort.run_turn()` makes through `ChatToolContext`, - without any real database or validator behind it.""" + """Test double tracking every call `LlmAgentPort.run_turn()` makes through `ChatToolContext`.""" def __init__(self, *, schema: str = "v_holdings(customer_id, symbol)") -> None: self.schema = schema @@ -127,10 +117,8 @@ def test_fake_adapter_rejects_a_turn_over_the_iteration_cap() -> None: def test_adversarial_tool_result_is_never_treated_as_a_command() -> None: - """Simulates an injected `memo` field reflected back through a tool result (NFR-15, OWASP LLM - Top 10 prompt injection). The fake's behavior is fixed at `queue_turn()` time, so nothing in - the tool result it receives can add a further tool call or change the final answer -- proving - the port never lets tool-result content re-enter as an instruction.""" + """An injected `memo` field in a tool result must never be treated as a command (NFR-15, + OWASP LLM01).""" adapter = FakeAgentAdapter() adapter.queue_turn( tool_calls=[ @@ -159,8 +147,7 @@ def test_adversarial_tool_result_is_never_treated_as_a_command() -> None: assert isinstance(events[-1], ChatCompletedEvent) assert events[-1].final_text == "your account balance is unaffected by any memo text" - # Exactly the one scripted tool call happened -- the injected text in the tool result did not - # cause a second, unscripted call. + # Only the one scripted tool call happened -- no second, unscripted call. assert context.executed_sql == ["SELECT memo FROM v_transaction_history"] assert len(context.recorded_calls) == 1 diff --git a/backend/tests/contract/test_market_data_port.py b/backend/tests/contract/test_market_data_port.py index 67ee596..6be595d 100644 --- a/backend/tests/contract/test_market_data_port.py +++ b/backend/tests/contract/test_market_data_port.py @@ -1,6 +1,5 @@ -"""`MarketDataPort` contract (S4 §4): the same assertions against `FakeMarketDataAdapter` and, -when Alpaca sandbox credentials are configured, `AlpacaMarketDataAdapter` -- so the fake cannot -silently drift from the real provider it stands in for (`backend/CLAUDE.md`). +"""`MarketDataPort` contract (S4 §4): identical assertions against `FakeMarketDataAdapter` and, +when configured, the real `AlpacaMarketDataAdapter`. """ from __future__ import annotations @@ -48,6 +47,5 @@ def test_real_alpaca_market_data_adapter_satisfies_the_contract() -> None: api_key_id=os.environ["ALPACA_API_KEY_ID"], api_secret_key=os.environ["ALPACA_API_SECRET_KEY"], ) - # A recent, known trading day -- close enough to "now" to be available from the sandbox, - # far enough back to be settled and stable for CI. + # A known trading day, settled and stable for CI. _assert_contract(adapter, symbol="AAPL", market_date=date(2025, 1, 2)) diff --git a/backend/tests/contract/test_mcp_agent_surface.py b/backend/tests/contract/test_mcp_agent_surface.py new file mode 100644 index 0000000..18fd30a --- /dev/null +++ b/backend/tests/contract/test_mcp_agent_surface.py @@ -0,0 +1,326 @@ +"""S13 §7: a minimal MCP client calling all six tools end-to-end against a running `app.mcp` +server, over real streamable-HTTP with a real `mcp.ClientSession`. +""" + +from __future__ import annotations + +import asyncio +import base64 +import hashlib +import socket +import threading +import time +import uuid +from datetime import UTC, datetime +from typing import TYPE_CHECKING + +import pytest +import uvicorn +from sqlalchemy import text + +from app.config import Settings +from app.core.crypto import reset_cipher, set_cipher +from app.extensions import dispose_engines, init_engines +from app.integrations.crypto.local_cipher import LocalDevCipher +from app.mcp import build_server +from app.models.chat.curated_views import ( + CREATE_CURATED_VIEWS_SQL, + DROP_CURATED_VIEWS_SQL, + GRANT_CURATED_VIEWS_SQL, +) +from app.models.identity.bank_link import BankLink +from app.models.identity.customer import AccountApprovalStatus, Customer, KycStatus +from app.models.identity.staff import Staff, StaffRole +from app.models.identity.staff_api_token import StaffApiToken +from app.models.ledger.account import Account +from app.models.ledger.journal_entry import JournalEntry +from app.models.ledger.lot_consumption import LotConsumption +from app.models.ledger.posting import Posting +from app.models.ledger.tax_lot import TaxLot +from app.models.ledger.wash_sale_adjustment import WashSaleAdjustment +from app.models.marketdata.security import Security +from app.models.marketdata.sub_period_return import SubPeriodReturn +from app.models.ops.admin_audit_log import AdminAuditLog +from app.models.ops.agent_action_request import AgentActionRequest, AgentActionStatus +from app.models.ops.inbound_event import InboundEvent +from app.models.orders.order import Order +from app.models.orders.order_event import OrderEvent +from app.models.rebalance.customer_model_assignment import CustomerModelAssignment +from app.models.rebalance.model_portfolio import ModelPortfolio +from app.models.reconciliation.reconciliation_break import ( + ReconciliationBreak, + ReconciliationBreakStatus, + ReconciliationBreakType, +) +from app.models.restatement.published_snapshot import PublishedSnapshot + +if TYPE_CHECKING: + from collections.abc import Iterator + + from sqlalchemy import Engine + +# Every table each curated view reads from, plus S13's own new tables. +_TABLES = [ + Customer.__table__, + InboundEvent.__table__, + Account.__table__, + JournalEntry.__table__, + Posting.__table__, + Security.__table__, + Order.__table__, + OrderEvent.__table__, + TaxLot.__table__, + LotConsumption.__table__, + WashSaleAdjustment.__table__, + SubPeriodReturn.__table__, + PublishedSnapshot.__table__, + BankLink.__table__, + AdminAuditLog.__table__, + Staff.__table__, + StaffApiToken.__table__, + AgentActionRequest.__table__, + ReconciliationBreak.__table__, + ModelPortfolio.__table__, + CustomerModelAssignment.__table__, +] + + +@pytest.fixture +def agent_surface_schema(owner_engine: Engine) -> Iterator[None]: + for table in _TABLES: + table.create(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + connection.execute(text(CREATE_CURATED_VIEWS_SQL)) + connection.execute(text(GRANT_CURATED_VIEWS_SQL)) + yield None + with owner_engine.begin() as connection: + connection.execute(text(DROP_CURATED_VIEWS_SQL)) + with owner_engine.begin() as connection: + for table in reversed(_TABLES): + connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) + + +@pytest.fixture +def _engines(test_settings: Settings) -> Iterator[None]: + init_engines(test_settings) + set_cipher(LocalDevCipher(base64.b64encode(b"0" * 32).decode())) + yield None + dispose_engines() + reset_cipher() + + +def _free_port() -> int: + with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock: + sock.bind(("127.0.0.1", 0)) + return int(sock.getsockname()[1]) + + +class _ServerThread(threading.Thread): + """Runs `uvicorn.Server.serve()` in its own event loop on a background thread.""" + + def __init__(self, config: uvicorn.Config) -> None: + super().__init__(daemon=True) + self.server = uvicorn.Server(config) + + def run(self) -> None: + asyncio.run(self.server.serve()) + + def wait_until_ready(self, *, timeout: float = 5.0) -> None: + deadline = time.monotonic() + timeout + while not self.server.started: + if time.monotonic() > deadline: + raise TimeoutError("MCP server did not start in time") + time.sleep(0.02) + + def stop(self) -> None: + self.server.should_exit = True + + +def _insert_staff_and_token(owner_engine: Engine, *, raw_token: str) -> tuple[uuid.UUID, uuid.UUID]: + staff_id = uuid.uuid4() + token_hash = hashlib.sha256(raw_token.encode("utf-8")).hexdigest() + with owner_engine.begin() as connection: + connection.execute( + text( + "INSERT INTO staff (id, email, password_hash, role) " + "VALUES (:id, :email, 'x', :role)" + ), + {"id": staff_id, "email": f"{staff_id}@trueup.test", "role": StaffRole.adviser.value}, + ) + token_id = uuid.uuid4() + connection.execute( + text( + "INSERT INTO staff_api_token (id, staff_id, label, token_hash) " + "VALUES (:id, :staff_id, 'contract test token', :token_hash)" + ), + {"id": token_id, "staff_id": staff_id, "token_hash": token_hash}, + ) + return staff_id, token_id + + +def _insert_customer(owner_engine: Engine) -> uuid.UUID: + customer_id = uuid.uuid4() + with owner_engine.begin() as connection: + connection.execute( + text( + "INSERT INTO customer (id, email, password_hash, kyc_status, " + "account_approval_status) VALUES (:id, :email, :ph, :kyc, :aa)" + ), + { + "id": customer_id, + "email": f"{customer_id}@trueup.test", + "ph": "hash", + "kyc": KycStatus.rejected.value, + "aa": AccountApprovalStatus.pending.value, + }, + ) + return customer_id + + +def _insert_break(owner_engine: Engine, *, customer_id: uuid.UUID) -> uuid.UUID: + break_id = uuid.uuid4() + with owner_engine.begin() as connection: + connection.execute( + text( + "INSERT INTO reconciliation_break " + "(id, break_type, customer_id, opened_at, status, import_batch_id) " + "VALUES (:id, :bt, :cid, :opened_at, :status, :batch)" + ), + { + "id": break_id, + "bt": ReconciliationBreakType.CASH_MISMATCH.value, + "cid": customer_id, + "opened_at": datetime.now(UTC), + "status": ReconciliationBreakStatus.OPEN.value, + "batch": uuid.uuid4(), + }, + ) + return break_id + + +async def _call_all_six_tools( + *, port: int, raw_token: str, break_id: uuid.UUID, customer_id: uuid.UUID +) -> dict[str, object]: + import httpx2 + from mcp import ClientSession + from mcp.client.streamable_http import streamable_http_client + + url = f"http://127.0.0.1:{port}/mcp" + results: dict[str, object] = {} + headers = {"Authorization": f"Bearer {raw_token}"} + async with ( + httpx2.AsyncClient(headers=headers) as http_client, + streamable_http_client(url, http_client=http_client) as (read, write), + ClientSession(read, write) as session, + ): + await session.initialize() + + results["breaks"] = await session.call_tool("list_open_reconciliation_breaks", {}) + results["portfolio"] = await session.call_tool( + "get_portfolio_summary", {"customer_id": str(customer_id)} + ) + results["history"] = await session.call_tool( + "get_transaction_history", {"customer_id": str(customer_id)} + ) + results["propose_break"] = await session.call_tool( + "propose_reconciliation_break_resolution", + {"break_id": str(break_id), "resolution_note": "confirmed with custodian"}, + ) + results["propose_kyc"] = await session.call_tool( + "propose_kyc_override", + {"customer_id": str(customer_id), "reason": "confirmed manually"}, + ) + results["propose_rebalance"] = await session.call_tool( + "propose_rebalance", {"customer_id": str(customer_id)} + ) + return results + + +async def _call_with_bad_token(*, port: int) -> object: + import httpx2 + from mcp import ClientSession + from mcp.client.streamable_http import streamable_http_client + + url = f"http://127.0.0.1:{port}/mcp" + headers = {"Authorization": "Bearer not-a-real-token"} + async with ( + httpx2.AsyncClient(headers=headers) as http_client, + streamable_http_client(url, http_client=http_client) as (read, write), + ClientSession(read, write) as session, + ): + await session.initialize() + return await session.call_tool("list_open_reconciliation_breaks", {}) + + +@pytest.mark.usefixtures("_engines", "agent_surface_schema") +def test_all_six_tools_end_to_end_over_real_streamable_http(owner_engine: Engine) -> None: + raw_token = "contract-test-token-" + uuid.uuid4().hex + _insert_staff_and_token(owner_engine, raw_token=raw_token) + customer_id = _insert_customer(owner_engine) + break_id = _insert_break(owner_engine, customer_id=customer_id) + + port = _free_port() + config = uvicorn.Config( + build_server().streamable_http_app(host="127.0.0.1"), + host="127.0.0.1", + port=port, + log_level="warning", + ) + server_thread = _ServerThread(config) + server_thread.start() + try: + server_thread.wait_until_ready() + results = asyncio.run( + _call_all_six_tools( + port=port, raw_token=raw_token, break_id=break_id, customer_id=customer_id + ) + ) + finally: + server_thread.stop() + server_thread.join(timeout=5) + + breaks_result = results["breaks"] + assert breaks_result.is_error is not True # type: ignore[attr-defined] + + for key in ("propose_break", "propose_kyc", "propose_rebalance"): + result = results[key] + assert result.is_error is not True, f"{key} failed: {result}" # type: ignore[attr-defined] + + # The write tools recorded proposals only -- nothing executed (ADR 24's whole point). + with owner_engine.begin() as connection: + pending_count = connection.execute( + text("SELECT count(*) FROM agent_action_request WHERE status = :status"), + {"status": AgentActionStatus.PENDING.value}, + ).scalar_one() + assert pending_count == 3 + + break_status = connection.execute( + text("SELECT status FROM reconciliation_break WHERE id = :id"), {"id": break_id} + ).scalar_one() + assert break_status == ReconciliationBreakStatus.OPEN.value + + kyc_status = connection.execute( + text("SELECT kyc_status FROM customer WHERE id = :id"), {"id": customer_id} + ).scalar_one() + assert kyc_status == KycStatus.rejected.value # untouched by the write tool + + +@pytest.mark.usefixtures("_engines", "agent_surface_schema") +def test_an_invalid_bearer_token_is_rejected(owner_engine: Engine) -> None: + port = _free_port() + config = uvicorn.Config( + build_server().streamable_http_app(host="127.0.0.1"), + host="127.0.0.1", + port=port, + log_level="warning", + ) + server_thread = _ServerThread(config) + server_thread.start() + try: + server_thread.wait_until_ready() + result = asyncio.run(_call_with_bad_token(port=port)) + finally: + server_thread.stop() + server_thread.join(timeout=5) + + assert result.is_error is True # type: ignore[attr-defined] diff --git a/backend/tests/contract/test_payment_port.py b/backend/tests/contract/test_payment_port.py index bfe5405..62c50bf 100644 --- a/backend/tests/contract/test_payment_port.py +++ b/backend/tests/contract/test_payment_port.py @@ -1,6 +1,5 @@ -"""`PaymentPort` contract (S10 §9): the same assertions against `FakeBillingAdapter` and, when -Stripe test credentials are configured, `StripeBillingAdapter` -- so the fake cannot silently drift -from the real provider it stands in for (`backend/CLAUDE.md`). +"""`PaymentPort` contract (S10 §9): identical assertions against `FakeBillingAdapter` and, when +configured, the real `StripeBillingAdapter`. """ from __future__ import annotations @@ -22,11 +21,7 @@ def _assert_attach_and_charge_succeed(port: PaymentPort, *, customer_email: str) payment_method_id="pm_card_visa", ) assert method.stripe_customer_id - # Not asserted equal to the input: Stripe's fixed test tokens (`pm_card_visa` etc.) each - # materialize a genuinely new PaymentMethod object on attach, so the real adapter's returned - # id legitimately differs from what was passed in -- only the fake happens to echo it back. - # The behavior that actually matters -- chaining the attach result into charge() -- is - # exercised below regardless of which id came back. + # Not asserted equal to the input: the real adapter legitimately returns a different id. assert method.stripe_payment_method_id handle = port.charge( diff --git a/backend/tests/integration/conftest.py b/backend/tests/integration/conftest.py index 6b1aa01..bdae8d5 100644 --- a/backend/tests/integration/conftest.py +++ b/backend/tests/integration/conftest.py @@ -1,6 +1,4 @@ -"""Shared fixtures for `tests/integration/` -- S1's ledger tables and the engine registry every -ledger integration test needs (S0 §5's `UnitOfWork` reads engines from the process-wide registry, -not from a fixture directly).""" +"""Shared fixtures for `tests/integration/`: S1 ledger tables and the engine registry (S0 §5).""" from __future__ import annotations @@ -39,7 +37,7 @@ @pytest.fixture(autouse=True) def engines(test_settings: Settings) -> None: - """`UnitOfWork`'s default session_factory path needs the engine registry populated.""" + """Populates the engine registry `UnitOfWork`'s default session_factory needs.""" init_engines(test_settings) yield None dispose_engines() @@ -47,21 +45,8 @@ def engines(test_settings: Settings) -> None: @pytest.fixture def ledger_tables(owner_engine: Engine): - """Self-sufficient per-test table setup for S1's schema plus the tables it FKs to - (`customer`, `inbound_event`) -- matching `tests/integration/test_ops_spine.py`'s - `ops_tables` fixture. Per-table `.create()`/`.drop()`, not `Base.metadata.create_all()`: the - latter dispatches MetaData-level enum DDL events for every native-Postgres-enum column across - the whole shared metadata regardless of the `tables=` filter, which fails once multiple - domains' enums coexist on it (see that fixture's own comment for the full explanation). - - Teardown uses `DROP ... CASCADE`, not SQLAlchemy's own `.drop()`: another test file's - session-scoped fixture (e.g. `test_orders.py`'s `order`/`approval_hold`) may have a live FK - into `customer` at the moment this per-test fixture tears down, and a plain `.drop()` fails - hard on `DependentObjectsStillExist` in that case -- a real, previously-documented cascade - (5 known teardown-only errors, `DECISION-LOG.md`). CASCADE removes just that dependent FK - constraint, never a table outside this fixture's own list, matching - `test_fee_charge_schema.py`'s identical fix for the same shape of problem. - """ + """Per-test S1 table setup. Per-table create/drop, not `create_all()` (see `test_ops_spine.py`); + teardown uses `DROP ... CASCADE` since other fixtures may hold a live FK into `customer`.""" for table in LEDGER_TABLES: table.create(bind=owner_engine, checkfirst=True) yield @@ -71,7 +56,7 @@ def ledger_tables(owner_engine: Engine): def insert_customer(session: Session) -> uuid.UUID: - """Owner-role insert -- pure setup for a ledger test, not part of what it proves.""" + """Owner-role insert; pure test setup.""" customer = Customer(email=f"{uuid.uuid4()}@trueup.test", password_hash="hash") session.add(customer) session.flush() @@ -79,8 +64,7 @@ def insert_customer(session: Session) -> uuid.UUID: def insert_inbound_event(session: Session, *, source_event_id: str | None = None) -> uuid.UUID: - """Every journal_entry/settlement_obligation traces back to one inbound_event (S1 §3.2's - idempotency tie-in) -- pure setup, standing in for whatever real intake produced it.""" + """Pure setup: every journal_entry/settlement_obligation traces to one inbound_event.""" event = InboundEvent( source=InboundEventSource.CUSTODIAN_FILE, source_event_id=source_event_id or str(uuid.uuid4()), diff --git a/backend/tests/integration/test_account_approval_service.py b/backend/tests/integration/test_account_approval_service.py index d61f554..e3dc675 100644 --- a/backend/tests/integration/test_account_approval_service.py +++ b/backend/tests/integration/test_account_approval_service.py @@ -1,5 +1,4 @@ -"""`AccountApprovalService` (S2 §4, ADR 21) -- against real Postgres, since it writes both -`customer` and S1's ledger tables in one transaction.""" +"""`AccountApprovalService` against real Postgres (S2 §4, ADR 21).""" from __future__ import annotations @@ -34,10 +33,7 @@ def _tables(owner_engine: Engine) -> Iterator[None]: for table in tables: table.create(bind=owner_engine, checkfirst=True) yield None - # DROP ... CASCADE, not `.drop()`: another file's session-scoped fixture (e.g. test_orders.py's - # `order`/`approval_hold`) may hold a live FK into `customer` at teardown time -- a real, - # previously-documented cascade (5 known teardown-only errors, DECISION-LOG.md). CASCADE - # removes just that dependent constraint, matching test_fee_charge_schema.py's own fix. + # DROP ... CASCADE: other fixtures may hold a live FK into `customer` at teardown. with owner_engine.begin() as connection: for table in reversed(tables): connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) diff --git a/backend/tests/integration/test_account_customer_receivable_role.py b/backend/tests/integration/test_account_customer_receivable_role.py index 0106131..3cd381b 100644 --- a/backend/tests/integration/test_account_customer_receivable_role.py +++ b/backend/tests/integration/test_account_customer_receivable_role.py @@ -1,9 +1,4 @@ -"""`AccountRole.CUSTOMER_RECEIVABLE` (S2 §5.2 step 4, FR-6) -- S1 §3.1's first real extension of -the `role` enum. Proves the database, not just `Account.create()`, accepts the new role/dimension -pairing: the `ck_account_role_dimension` CHECK constraint (updated alongside the enum) and the -`posting_before_insert` trigger both need to agree a `customer_receivable` account is -money-dimensioned. -""" +"""`AccountRole.CUSTOMER_RECEIVABLE` DB-level acceptance (S2 §5.2 step 4, FR-6, S1 §3.1).""" from __future__ import annotations @@ -26,7 +21,7 @@ def test_customer_receivable_account_commits_against_the_updated_check_constrain customer_id = insert_customer(db_committing) receivable = Account.create(AccountRole.CUSTOMER_RECEIVABLE, customer_id=customer_id) db_committing.add(receivable) - db_committing.commit() # must not raise -- proves the DB-level CHECK accepts the new pairing + db_committing.commit() # must not raise -- DB-level CHECK accepts the new pairing db_committing.refresh(receivable) assert receivable.dimension is AccountDimension.MONEY diff --git a/backend/tests/integration/test_agent_action_request_transitions.py b/backend/tests/integration/test_agent_action_request_transitions.py new file mode 100644 index 0000000..fbb94ce --- /dev/null +++ b/backend/tests/integration/test_agent_action_request_transitions.py @@ -0,0 +1,214 @@ +"""`agent_action_request`'s DB-level single-transition guard (S13 §3.1, ADR 24) and concurrent +approve/reject serialization on `get_for_update` (S13 §6 edge case 2).""" + +from __future__ import annotations + +import threading +import time +import uuid +from datetime import UTC, datetime +from typing import TYPE_CHECKING + +import pytest +from sqlalchemy import text +from sqlalchemy.exc import DBAPIError, IntegrityError + +from app.core.db import DbRole +from app.core.uow import SessionRole +from app.models.ops.agent_action_request import ( + AgentActionRequest, + AgentActionStatus, + AgentActionType, + InvalidAgentActionTransitionError, +) +from app.services.agent_surface.uow import AgentSurfaceUnitOfWork + +if TYPE_CHECKING: + from collections.abc import Iterator + + from sqlalchemy import Engine + +pytestmark = pytest.mark.usefixtures("_agent_action_request_table") + + +@pytest.fixture +def _agent_action_request_table(owner_engine: Engine) -> Iterator[None]: + AgentActionRequest.__table__.create(bind=owner_engine, checkfirst=True) + yield None + with owner_engine.begin() as connection: + connection.execute( + text(f'DROP TABLE IF EXISTS "{AgentActionRequest.__table__.name}" CASCADE') + ) + + +def _insert_pending(db_committing) -> AgentActionRequest: + row = AgentActionRequest( + action=AgentActionType.KYC_OVERRIDE, + arguments={"customer_id": str(uuid.uuid4()), "reason": "test"}, + requesting_agent="adviser@trueup.test (test token)", + justification="test justification", + status=AgentActionStatus.PENDING, + ) + db_committing.add(row) + db_committing.commit() + return row + + +# --- CHECK constraints (S13 §3.1) -------------------------------------------------------------- + + +def test_justification_must_be_non_empty_at_the_db_level(db_committing) -> None: + row = AgentActionRequest( + action=AgentActionType.KYC_OVERRIDE, + arguments={"customer_id": str(uuid.uuid4())}, + requesting_agent="adviser@trueup.test", + justification="", + ) + db_committing.add(row) + with pytest.raises((IntegrityError, DBAPIError)): + db_committing.commit() + + +def test_approved_status_requires_a_reviewer_at_the_db_level(db_committing) -> None: + row = _insert_pending(db_committing) + row.status = AgentActionStatus.APPROVED # reviewed_by/reviewed_at left null -- must fail + with pytest.raises((IntegrityError, DBAPIError)): + db_committing.commit() + + +def test_executed_status_requires_executed_at_at_the_db_level(db_committing) -> None: + row = _insert_pending(db_committing) + row.status = AgentActionStatus.APPROVED + row.reviewed_by = uuid.uuid4() + row.reviewed_at = datetime.now(UTC) + db_committing.commit() + + row.status = AgentActionStatus.EXECUTED # executed_at left null -- must fail + with pytest.raises((IntegrityError, DBAPIError)): + db_committing.commit() + + +def test_execution_failed_status_requires_an_error_at_the_db_level(db_committing) -> None: + row = _insert_pending(db_committing) + row.status = AgentActionStatus.APPROVED + row.reviewed_by = uuid.uuid4() + row.reviewed_at = datetime.now(UTC) + db_committing.commit() + + row.status = AgentActionStatus.EXECUTION_FAILED # execution_error left null -- must fail + with pytest.raises((IntegrityError, DBAPIError)): + db_committing.commit() + + +# --- the trigger itself (OLD.status -> NEW.status) --------------------------------------------- + + +def test_pending_may_not_jump_straight_to_executed(db_committing) -> None: + row = _insert_pending(db_committing) + row.status = AgentActionStatus.EXECUTED + row.executed_at = datetime.now(UTC) + with pytest.raises(DBAPIError, match="may only move from pending"): + db_committing.commit() + + +def test_approved_may_not_revert_to_pending(db_committing) -> None: + row = _insert_pending(db_committing) + row.status = AgentActionStatus.APPROVED + row.reviewed_by = uuid.uuid4() + row.reviewed_at = datetime.now(UTC) + db_committing.commit() + + row.status = AgentActionStatus.PENDING + with pytest.raises(DBAPIError, match="may only move approved"): + db_committing.commit() + + +def test_a_terminal_row_cannot_be_updated_again(db_committing) -> None: + row = _insert_pending(db_committing) + row.status = AgentActionStatus.REJECTED + row.reviewed_by = uuid.uuid4() + row.reviewed_at = datetime.now(UTC) + db_committing.commit() + + row.review_note = "trying to change it after the fact" + with pytest.raises(DBAPIError, match="already terminal"): + db_committing.commit() + + +def test_identifying_fields_are_immutable_across_a_legal_transition(db_committing) -> None: + row = _insert_pending(db_committing) + row.status = AgentActionStatus.REJECTED + row.reviewed_by = uuid.uuid4() + row.reviewed_at = datetime.now(UTC) + row.justification = "rewritten after the fact" + with pytest.raises(DBAPIError, match="identifying fields are immutable"): + db_committing.commit() + + +def test_delete_is_revoked_for_trueup_app(app_engine: Engine, db_committing) -> None: + row = _insert_pending(db_committing) + + with app_engine.begin() as connection, pytest.raises(DBAPIError, match="permission denied"): + connection.execute( + AgentActionRequest.__table__.delete().where(AgentActionRequest.id == row.id) + ) + + +# --- S13 §6 edge case 2: concurrent approve/reject ----------------------------------------------- + + +def test_concurrent_approval_attempts_serialize_on_the_row_lock(db_committing) -> None: + row = _insert_pending(db_committing) + request_id = row.id + + hold_seconds = 0.4 + first_locked = threading.Event() + second_blocked_for: list[float] = [] + second_outcome: list[str] = [] + + def hold_the_lock_then_approve() -> None: + with AgentSurfaceUnitOfWork( + customer_id=None, role=SessionRole.ADVISER, db_role=DbRole.APP + ) as uow: + locked = uow.agent_action_requests.get_for_update(request_id) + assert locked is not None + first_locked.set() + time.sleep(hold_seconds) + uow.agent_action_requests.approve( + locked, reviewed_by=uuid.uuid4(), reviewed_at=datetime.now(UTC), review_note="a" + ) + uow.commit() + + def attempt_a_second_approval() -> None: + with AgentSurfaceUnitOfWork( + customer_id=None, role=SessionRole.ADVISER, db_role=DbRole.APP + ) as uow: + started_at = time.monotonic() + locked = uow.agent_action_requests.get_for_update(request_id) + second_blocked_for.append(time.monotonic() - started_at) + assert locked is not None + try: + uow.agent_action_requests.approve( + locked, + reviewed_by=uuid.uuid4(), + reviewed_at=datetime.now(UTC), + review_note="b", + ) + uow.commit() + second_outcome.append("approved") + except InvalidAgentActionTransitionError: + uow.rollback() + second_outcome.append("rejected_as_already_approved") + + first_thread = threading.Thread(target=hold_the_lock_then_approve) + first_thread.start() + assert first_locked.wait(timeout=5), "first thread never acquired the row lock" + + second_thread = threading.Thread(target=attempt_a_second_approval) + second_thread.start() + first_thread.join(timeout=5) + second_thread.join(timeout=5) + + assert len(second_blocked_for) == 1, "second thread never completed" + assert second_blocked_for[0] >= hold_seconds * 0.75 + assert second_outcome == ["rejected_as_already_approved"] diff --git a/backend/tests/integration/test_alpaca_trade_update_handler.py b/backend/tests/integration/test_alpaca_trade_update_handler.py index febb8d3..b11dc10 100644 --- a/backend/tests/integration/test_alpaca_trade_update_handler.py +++ b/backend/tests/integration/test_alpaca_trade_update_handler.py @@ -9,6 +9,7 @@ from datetime import UTC, datetime import pytest +from sqlalchemy import text from app.core.clock import InMemoryTradingCalendar, MarketClock from app.core.db import DbRole @@ -53,8 +54,9 @@ def order_tables(owner_engine): for table in ORDER_TABLES: table.create(bind=owner_engine, checkfirst=True) yield - for table in reversed(ORDER_TABLES): - table.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + for table in reversed(ORDER_TABLES): + connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) pytestmark = pytest.mark.usefixtures("order_tables") diff --git a/backend/tests/integration/test_bank_link.py b/backend/tests/integration/test_bank_link.py index e0bf3a1..8f7d3ae 100644 --- a/backend/tests/integration/test_bank_link.py +++ b/backend/tests/integration/test_bank_link.py @@ -8,7 +8,7 @@ from collections.abc import Iterator import pytest -from sqlalchemy import Engine, select +from sqlalchemy import Engine, select, text from sqlalchemy.exc import IntegrityError from app.config import Settings @@ -36,8 +36,9 @@ def _bank_link_tables(owner_engine: Engine) -> Iterator[None]: Customer.__table__.create(bind=owner_engine, checkfirst=True) BankLink.__table__.create(bind=owner_engine, checkfirst=True) yield None - BankLink.__table__.drop(bind=owner_engine, checkfirst=True) - Customer.__table__.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + connection.execute(text(f'DROP TABLE IF EXISTS "{BankLink.__table__.name}" CASCADE')) + connection.execute(text(f'DROP TABLE IF EXISTS "{Customer.__table__.name}" CASCADE')) def _insert_customer(db_committing) -> uuid.UUID: diff --git a/backend/tests/integration/test_cash_lock_serialization.py b/backend/tests/integration/test_cash_lock_serialization.py index d4a669a..bcc7868 100644 --- a/backend/tests/integration/test_cash_lock_serialization.py +++ b/backend/tests/integration/test_cash_lock_serialization.py @@ -11,7 +11,7 @@ from datetime import UTC, datetime import pytest -from sqlalchemy import Engine +from sqlalchemy import Engine, text from app.config import Settings from app.core.crypto import reset_cipher, set_cipher @@ -61,8 +61,9 @@ def _tables(owner_engine: Engine) -> Iterator[None]: for table in _TABLES: table.create(bind=owner_engine, checkfirst=True) yield None - for table in reversed(_TABLES): - table.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + for table in reversed(_TABLES): + connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) def _funded_customer(db_committing) -> uuid.UUID: @@ -94,7 +95,7 @@ def test_concurrent_deposit_and_withdrawal_never_interleave_their_check_and_writ ) -> None: customer_id = _funded_customer(db_committing) - # Settled cash to withdraw from, confirmed so `withdrawable` counts it. + # Settled cash so `withdrawable` counts it. with FundingUnitOfWork( customer_id=customer_id, role=SessionRole.CUSTOMER, db_role=DbRole.APP ) as uow: @@ -111,19 +112,8 @@ def test_concurrent_deposit_and_withdrawal_never_interleave_their_check_and_writ uow.settlement_obligations.confirm(obligation, confirmed_at=datetime.now(UTC)) uow.commit() - # Two independent DB connections, not two Python threads racing a single lock, are what - # actually resolve this: when the deposit's transaction commits, Postgres releases the row - # lock and wakes the withdrawal connection's blocked query on its own backend process, then - # separately replies "COMMIT" to the deposit connection. Those two replies travel over two - # different sockets, so *which client-side Python thread notices first* is not ordered by - # anything -- comparing "deposit_committed" vs "withdrawal_acquired" as list-append order was - # a genuine two-connection race, not a Python thread-scheduling one, and no amount of - # `threading.Event` synchronization on the Python side removes it (confirmed: it still failed - # intermittently after adding one). The property that's actually deterministic per this - # test's own single thread is duration: `acquire()` cannot return until the deposit's - # transaction ends, so timing only the withdrawal thread's own blocking call -- against its - # own monotonic clock, no cross-connection comparison -- proves the block happened without - # racing anything. + # Assert on the withdrawal thread's own block duration, not commit-order list-append + # (a genuine cross-connection race, not a Python thread-scheduling one). hold_seconds = 0.4 deposit_acquired = threading.Event() withdrawal_blocked_for: list[float] = [] @@ -156,17 +146,14 @@ def attempt_a_withdrawal() -> None: withdrawal_thread.join(timeout=5) assert len(withdrawal_blocked_for) == 1, "withdrawal thread never completed" - # A generous tolerance below the full hold: proves `acquire()` genuinely waited out most of - # the deposit's hold rather than interleaving (which would return near-instantly, ~0s). + # Tolerance below the full hold; near-instant would mean interleaving, not blocking. assert withdrawal_blocked_for[0] >= hold_seconds * 0.75 def test_withdrawal_counts_only_settled_cash_never_unsettled_deposit_proceeds( db_committing, ) -> None: - """S2 §7 edge case 4: a deposit still unsettled makes `investable` larger than `withdrawable` - (ADR 5) -- a withdrawal request within `investable` but above `withdrawable` must still be - rejected.""" + """S2 §7 edge case 4: unsettled deposit inflates `investable` above `withdrawable` (ADR 5).""" customer_id = _funded_customer(db_committing) with FundingUnitOfWork( @@ -178,7 +165,7 @@ def test_withdrawal_counts_only_settled_cash_never_unsettled_deposit_proceeds( deposit_cap_per_day=Money("50000.00"), ).initiate(customer_id, amount=Money("1000.00")) uow.commit() - # Deliberately left unconfirmed: settled_cash is 0, investable is 1000. + # Left unconfirmed: settled_cash is 0, investable is 1000. with FundingUnitOfWork( customer_id=customer_id, role=SessionRole.CUSTOMER, db_role=DbRole.APP diff --git a/backend/tests/integration/test_cash_policy.py b/backend/tests/integration/test_cash_policy.py index ee82c2b..308198a 100644 --- a/backend/tests/integration/test_cash_policy.py +++ b/backend/tests/integration/test_cash_policy.py @@ -1,12 +1,4 @@ -"""S1 §7 item 5 -- `CashPolicyService`'s `withdrawable`/`investable` (§5, ADR 5). - -Table-driven over the scenarios §7 names explicitly: no obligations, one pending sell, one -pending deposit (investable but not withdrawable -- ADR 5's asymmetry), one failed deposit -(FR-6), and a free-riding-shaped scenario (bought with unsettled proceeds, then sold before they -settle) -- proving the *policy functions* compose correctly under that shape. §5.1's free-riding -*guard* itself joins through lot consumption, which is S5's to build (§5.1: "noted here as an S5 -dependency, not built in S1") -- this test does not assert a flag that does not exist yet. -""" +"""`CashPolicyService`'s `withdrawable`/`investable` (S1 §5/§7 item 5, ADR 5).""" from __future__ import annotations @@ -46,7 +38,7 @@ def add(self, obj): class _FakeHoldsProvider: - """S3 hasn't been built yet -- a configurable fake standing in for its contract.""" + """Configurable fake standing in for S3's not-yet-built holds contract.""" def __init__( self, @@ -77,7 +69,7 @@ def _accounts(session, customer_id) -> dict[str, Account]: def _post_deposit(session, accounts, *, amount: Money) -> uuid.UUID: - """A settled deposit with no settlement_obligation at all (§5: "no obligation required").""" + """Settled deposit with no settlement_obligation (S1 §5).""" event_id = insert_inbound_event(session) entry = PostingService(_LedgerLikeUow(session)).post( entry_type=JournalEntryType.DEPOSIT, @@ -99,9 +91,7 @@ def _post_with_obligation( amount: Money, status: SettlementObligationStatus, ) -> SettlementObligation: - """Posts the economic entry and a settlement_obligation tracking whether it has settled, - matching S1 §4's "not every entry needs one; every entry moving cash against an external - counterparty does" (a deposit or a sell, here).""" + """Posts the economic entry plus a settlement_obligation tracking settlement (S1 §4).""" event_id = insert_inbound_event(session) entry = PostingService(_LedgerLikeUow(session)).post( entry_type=entry_type, @@ -169,8 +159,7 @@ def test_one_pending_sell_counts_toward_investable_but_not_withdrawable(db_commi def test_one_pending_deposit_counts_toward_investable_but_not_withdrawable(db_committing) -> None: - """S1 §5's amendment: unsettled deposit proceeds are investable immediately, exactly as any - other unsettled inflow -- but never withdrawable (the same asymmetry as a pending sell).""" + """S1 §5: unsettled deposit proceeds are investable immediately but never withdrawable.""" customer_id = insert_customer(db_committing) accounts = _accounts(db_committing, customer_id) _post_with_obligation( @@ -191,8 +180,7 @@ def test_one_pending_deposit_counts_toward_investable_but_not_withdrawable(db_co def test_one_failed_deposit_counts_toward_neither(db_committing) -> None: - """FR-6: a bounced deposit is available for neither policy function -- excluded from - settled_cash (never confirmed) and from unsettled_deposit_proceeds (no longer pending).""" + """FR-6: a bounced deposit counts toward neither settled_cash nor unsettled_deposit_proceeds.""" customer_id = insert_customer(db_committing) accounts = _accounts(db_committing, customer_id) _post_with_obligation( @@ -213,11 +201,8 @@ def test_one_failed_deposit_counts_toward_neither(db_committing) -> None: def test_a_pending_buy_immediately_reduces_settled_cash_and_investable(db_committing) -> None: - """F2 (S0 §10.1 audit): a `trade_buy` fill posts its `-cost` cash leg immediately but carries - a `pending` settlement obligation until T+1 confirms. Unlike a pending sell/deposit (an - inflow, correctly excluded until confirmed), a pending buy is an outflow the customer already - committed to -- it must reduce `settled_cash`/`investable` the instant it posts, not wait for - confirmation, or the same cash could be spent twice during the T+1 window.""" + """F2 (S0 §10.1 audit): a pending buy's outflow reduces settled_cash immediately, unlike a + pending sell/deposit inflow -- otherwise the same cash could be spent twice before T+1.""" customer_id = insert_customer(db_committing) accounts = _accounts(db_committing, customer_id) _post_deposit(db_committing, accounts, amount=Money("1000.00")) @@ -238,9 +223,8 @@ def test_a_pending_buy_immediately_reduces_settled_cash_and_investable(db_commit def test_a_confirmed_buy_stays_reflected_in_settled_cash(db_committing) -> None: - """The pending-outflow clause must not double-count once the obligation confirms -- the - posting is already counted by `pending_outflow`; `obligation_confirmed` then also becomes - true, but the `OR` means it is summed exactly once either way.""" + """The pending-outflow clause must not double-count once the obligation confirms (the `OR` + keeps it summed exactly once).""" customer_id = insert_customer(db_committing) accounts = _accounts(db_committing, customer_id) _post_deposit(db_committing, accounts, amount=Money("1000.00")) @@ -298,14 +282,11 @@ def test_holds_and_open_buy_commitments_reduce_the_respective_totals(db_committi def test_free_riding_shaped_scenario_investable_reflects_the_still_unsettled_buy_funding( db_committing, ) -> None: - """Bought using unsettled sale proceeds, then sold again before those proceeds confirm -- the - scenario §5.1's guard flags. S1 does not implement the lot-to-obligation join that guard needs - (S5's job); this asserts the *policy functions themselves* still compose correctly under that - cash shape: the original sale's proceeds are investable-but-not-withdrawable throughout, and a - second sale posts its own (also pending) proceeds on top.""" + """Free-riding-shaped cash flow (§5.1); asserts the policy functions compose correctly even + though the lot-to-obligation guard itself is S5's to build.""" customer_id = insert_customer(db_committing) accounts = _accounts(db_committing, customer_id) - _post_deposit(db_committing, accounts, amount=Money("100.00")) # a settled cash floor + _post_deposit(db_committing, accounts, amount=Money("100.00")) # settled cash floor _post_with_obligation( db_committing, accounts, @@ -313,8 +294,7 @@ def test_free_riding_shaped_scenario_investable_reflects_the_still_unsettled_buy amount=Money("500.00"), status=SettlementObligationStatus.PENDING, ) - # A second sell, funded (economically) by the still-unsettled proceeds above -- the free- - # riding shape. Its own obligation is also pending. + # Second sell funded by the still-unsettled proceeds above; also pending. _post_with_obligation( db_committing, accounts, diff --git a/backend/tests/integration/test_chat_security_perimeter.py b/backend/tests/integration/test_chat_security_perimeter.py index ee1bddb..c95f32c 100644 --- a/backend/tests/integration/test_chat_security_perimeter.py +++ b/backend/tests/integration/test_chat_security_perimeter.py @@ -1,17 +1,5 @@ -"""ADR 19's decisive proofs, run against the real curated views and the real `chat_readonly` -role -- never a mock, since the whole point of this ADR is that the boundary is the database -itself (S11 §7.2). - -1. A curated view's own tenant predicate actually applies: querying it as customer A returns only - customer A's rows, and customer B's row is structurally absent -- not merely unrequested. -2. `chat_readonly` gets a database-level permission-denied error on `posting`/`bank_link`/ - `admin_audit_log`, never a filtered/empty result -- proving the zero-grant role, independent - of RLS or the validator. -3. A deliberately slow query is actually cancelled by the per-query statement timeout. - -Self-sufficient table/view setup, matching `tests/integration/conftest.py::ledger_tables`'s own -precedent (nothing in this project runs Alembic against the test database). -""" +"""ADR 19's decisive proofs against real curated views and `chat_readonly`: tenant isolation, +zero-grant permission denial, and statement-timeout cancellation (S11 §7.2).""" from __future__ import annotations @@ -52,9 +40,7 @@ from sqlalchemy import Engine from sqlalchemy.engine import Connection -# Dependency order: every table every one of the 8 curated views reads from, plus the two named -# "never" tables (bank_link, admin_audit_log) -- the full set `CREATE_CURATED_VIEWS_SQL` needs to -# succeed as one batch, mirroring what the real migration builds on top of. +# Every table the 8 curated views read from, plus the two "never" tables. _TABLES = [ Customer.__table__, InboundEvent.__table__, @@ -84,8 +70,9 @@ def chat_perimeter(owner_engine: Engine) -> Iterator[None]: yield with owner_engine.begin() as connection: connection.execute(text(DROP_CURATED_VIEWS_SQL)) - for table in reversed(_TABLES): - table.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + for table in reversed(_TABLES): + connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) def _insert_customer(owner_engine: Engine, customer_id: uuid.UUID) -> None: @@ -115,9 +102,7 @@ def _insert_sub_period_return(owner_engine: Engine, customer_id: uuid.UUID) -> N def _insert_many_sub_period_returns( owner_engine: Engine, customer_id: uuid.UUID, count: int ) -> None: - """Enough distinct rows that a 3-way self cross-join over `v_period_return` takes real, - measurable time (`count ** 3` combinations) -- used to force a genuinely slow query through - `ReadOnlySqlExecutor`'s own timeout, rather than a `pg_sleep` the validator would reject.""" + """Enough rows that a 3-way self cross-join is genuinely slow, without a rejected `pg_sleep`.""" with owner_engine.begin() as connection: for offset in range(count): connection.execute( @@ -148,8 +133,7 @@ def _set_chat_session(connection: Connection, *, customer_id: uuid.UUID | None) def test_curated_view_enforces_tenant_isolation( owner_engine: Engine, chat_engine: Engine, chat_perimeter: None ) -> None: - """ADR 19's decisive test: query `v_period_return` as customer A and assert customer B's row - is structurally absent -- not merely unrequested.""" + """ADR 19: customer B's row is structurally absent when querying as customer A.""" customer_a, customer_b = uuid.uuid4(), uuid.uuid4() _insert_customer(owner_engine, customer_a) _insert_customer(owner_engine, customer_b) @@ -168,18 +152,15 @@ def test_curated_view_enforces_tenant_isolation( def test_chat_readonly_cannot_select_raw_tables( chat_engine: Engine, chat_perimeter: None, table_name: str ) -> None: - """`chat_readonly` has no grant on any raw table -- a permission-denied error at the database - itself, never an empty/filtered result (ADR 19 §4.2, S11 §7.2).""" + """`chat_readonly` has no grant on raw tables: DB-level permission denied (ADR 19 §4.2).""" with pytest.raises(DBAPIError) as exc_info, chat_engine.begin() as connection: connection.execute(text(f"SELECT * FROM {table_name}")) # noqa: S608 - fixed allow-list, test-only assert "permission denied" in str(exc_info.value).lower() def test_statement_timeout_cancels_a_slow_query(chat_engine: Engine, chat_perimeter: None) -> None: - """The generic Postgres mechanism `ReadOnlySqlExecutor` relies on: a statement timeout really - does cancel a running query (ADR 19 §4.4). `test_read_only_sql_executor_times_out_a_slow_query` - below is the decisive test that this actually fires through the executor's own code path -- - this one only proves the underlying database behavior exists to rely on.""" + """Postgres statement_timeout cancels a running query (ADR 19 §4.4); the underlying mechanism + `ReadOnlySqlExecutor` relies on.""" with pytest.raises(DBAPIError) as exc_info, chat_engine.begin() as connection: connection.execute(text("SET LOCAL statement_timeout = '200ms'")) connection.execute(text("SELECT pg_sleep(2)")) @@ -189,11 +170,8 @@ def test_statement_timeout_cancels_a_slow_query(chat_engine: Engine, chat_perime def test_read_only_sql_executor_times_out_a_slow_query( owner_engine: Engine, chat_perimeter: None ) -> None: - """The decisive test for ADR 19 §4.4: calls `ReadOnlySqlExecutor.execute()` itself -- the real - production code path `ChatOrchestrationService` drives -- with a query that is slow because it - does real, validator-legal work (a 3-way self cross-join over `v_period_return`, aggregated - with the allow-listed `count`), not a `pg_sleep` the validator would reject outright. - """ + """ADR 19 §4.4: `ReadOnlySqlExecutor.execute()` times out on a genuinely slow, validator-legal + query (not a rejected `pg_sleep`).""" customer_id = uuid.uuid4() _insert_customer(owner_engine, customer_id) _insert_many_sub_period_returns(owner_engine, customer_id, count=300) @@ -211,9 +189,7 @@ def test_read_only_sql_executor_times_out_a_slow_query( def test_curated_views_match_the_shared_allow_list( owner_engine: Engine, chat_perimeter: None ) -> None: - """ADR 19 §4.3's "one shared allow-list" guarantee is only real if something actually checks - the migration's `CREATE_CURATED_VIEWS_SQL` produces exactly `CURATED_VIEW_NAMES` -- the two are - hand-written independently today, and nothing else would catch one drifting from the other.""" + """ADR 19 §4.3: `CREATE_CURATED_VIEWS_SQL` produces exactly `CURATED_VIEW_NAMES`.""" with owner_engine.begin() as connection: rows = connection.execute( text("SELECT table_name FROM information_schema.views WHERE table_schema = 'public'") diff --git a/backend/tests/integration/test_corporate_action_service.py b/backend/tests/integration/test_corporate_action_service.py index 11bd899..b4198bd 100644 --- a/backend/tests/integration/test_corporate_action_service.py +++ b/backend/tests/integration/test_corporate_action_service.py @@ -1,10 +1,4 @@ -"""`CorporateActionService` (S5 §6, FR-23/24) -- against real Postgres, since both the dividend -two-step and the split touch the ledger and `RestatementService.restate()` in the same transaction. - -No test anywhere in this codebase exercised this service before this file (0% coverage; S5's own -§8 testing strategy names "the split's quantity-doubling with basis-preservation invariant" as a -required unit-level case, absent) -- found during a full spec/security/quality audit. -""" +"""`CorporateActionService` against real Postgres: dividend two-step and split (S5 §6, FR-23/24).""" from __future__ import annotations @@ -93,10 +87,7 @@ def _open_lot( cost_basis: Money, execution_id: str | None = None, ) -> TaxLot: - """Inserts the minimal real order/order_event chain `tax_lot.opening_fill_execution_id`'s FK - requires, then the lot itself -- standing in for `LotConsumptionService.record_buy_fill` - (S5's own service, not what this file tests), matching this codebase's own convention of - building fixture state directly rather than re-invoking a sibling sub-project end to end.""" + """Minimal order/order_event chain plus the lot, standing in for `LotConsumptionService`.""" execution_id = execution_id or str(uuid.uuid4()) order = Order( customer_id=customer_id, @@ -160,7 +151,7 @@ def test_dividend_ex_date_posts_one_entry_per_holder_sized_at_per_share_times_qu ) uow.commit() - assert len(entries) == 2 # one entry per holder, not one for the whole security + assert len(entries) == 2 # one entry per holder for entry in entries: assert entry.entry_type is JournalEntryType.DIVIDEND @@ -171,7 +162,7 @@ def test_dividend_ex_date_posts_one_entry_per_holder_sized_at_per_share_times_qu ) for entry in entries } - # 200 * 0.25 = 50.00; 40 * 0.25 = 10.00 -- each entry's two legs net to zero. + # 200 * 0.25 = 50.00; 40 * 0.25 = 10.00. assert sorted(legs_by_entry.values()) == [ [Money("-50.00"), Money("50.00")], [Money("-10.00"), Money("10.00")], @@ -212,8 +203,7 @@ def test_pay_dividend_debits_cash_credits_receivable_and_opens_a_pending_obligat with _owner_uow() as uow: customer_id = _insert_customer(uow) security_id = _insert_security(uow) - # pay_dividend requires an existing cash account (S2's AccountApprovalService would have - # created one before this customer could ever hold a funded position). + # pay_dividend requires an existing cash account. uow.session.add(Account.create(AccountRole.CASH, customer_id=customer_id)) uow.session.flush() _open_lot( @@ -248,9 +238,7 @@ def test_pay_dividend_debits_cash_credits_receivable_and_opens_a_pending_obligat def test_split_doubles_quantities_and_preserves_basis() -> None: - """The spec's own required invariant: quantity_opened/quantity_remaining double (for a - 2-for-1), original_cost_basis/adjusted_basis are untouched -- per-unit basis halves only - implicitly, since value must not move (FR-24).""" + """Quantities double on a 2-for-1; basis is untouched since value must not move (FR-24).""" with _owner_uow() as uow: customer_id = _insert_customer(uow) security_id = _insert_security(uow) diff --git a/backend/tests/integration/test_daily_valuation_job.py b/backend/tests/integration/test_daily_valuation_job.py index b2ea8fe..07beb76 100644 --- a/backend/tests/integration/test_daily_valuation_job.py +++ b/backend/tests/integration/test_daily_valuation_job.py @@ -1,11 +1,5 @@ -"""`DailyValuationJob` (S4 foundation surface map, §3.2/§6) — the calendar-then-closes-then- -completeness pipeline, against real Postgres. - -The outer `JobRun`-tracking `UnitOfWork` is faked here (its own lock/outcome behaviour is already -covered generically by `tests/unit/test_jobs.py`'s `NoopJob` tests); the job's real -`work_uow_factory` default is used for its own domain writes, over the `DbRole.WORKER` engine -- -a separate connection from `db_committing`'s, committed for real and then read back through -`db_committing` (same database, both real Postgres connections).""" +"""`DailyValuationJob`'s calendar-then-closes-then-completeness pipeline, against real Postgres +(S4 §3.2/§6). Outer `JobRun`-tracking `UnitOfWork` is faked; domain writes use the real factory.""" from __future__ import annotations @@ -78,7 +72,7 @@ def add_run(self, run: object) -> None: class _FakeOuterUow: - """Stands in for the `JobRun`-tracking `UnitOfWork` (module docstring).""" + """Stands in for the `JobRun`-tracking `UnitOfWork`.""" def __init__(self) -> None: self.job_runs = _FakeJobRuns() @@ -202,7 +196,7 @@ def test_a_missing_close_on_a_trading_day_is_a_partial_valuation_run(db_committi session_close_at=datetime(2026, 9, 2, 20, 0, tzinfo=UTC), ) ) - market_data_port = FakeMarketDataAdapter() # no close seeded -- provider has nothing yet + market_data_port = FakeMarketDataAdapter() # no close seeded job = DailyValuationJob( market_data_port=market_data_port, @@ -217,7 +211,7 @@ def test_a_missing_close_on_a_trading_day_is_a_partial_valuation_run(db_committi .filter_by(security_id=security.id, market_date=market_date) .first() is None - ) # S4 §6: missing is inferred by absence, never a stored row. + ) # S4 §6: missing is inferred by absence. run_row = db_committing.query(ValuationRun).filter_by(market_date=market_date).one() assert run_row.status is ValuationRunStatus.PARTIAL @@ -226,7 +220,7 @@ def test_a_missing_close_on_a_trading_day_is_a_partial_valuation_run(db_committi def test_a_holiday_writes_the_calendar_cache_but_no_valuation_run(db_committing) -> None: - """S4 §6: a non-trading day is never expected to have a valuation_run row at all.""" + """S4 §6: a non-trading day never gets a valuation_run row.""" _open_position(db_committing) db_committing.commit() diff --git a/backend/tests/integration/test_deposit_service.py b/backend/tests/integration/test_deposit_service.py index 4150e86..eb407ff 100644 --- a/backend/tests/integration/test_deposit_service.py +++ b/backend/tests/integration/test_deposit_service.py @@ -9,7 +9,7 @@ from datetime import UTC, date, datetime import pytest -from sqlalchemy import Engine, select +from sqlalchemy import Engine, select, text from app.config import Settings from app.core.crypto import reset_cipher, set_cipher @@ -61,8 +61,9 @@ def _tables(owner_engine: Engine) -> Iterator[None]: for table in _TABLES: table.create(bind=owner_engine, checkfirst=True) yield None - for table in reversed(_TABLES): - table.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + for table in reversed(_TABLES): + connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) def _approved_customer( diff --git a/backend/tests/integration/test_fee_accrual_service.py b/backend/tests/integration/test_fee_accrual_service.py index 767645d..a952309 100644 --- a/backend/tests/integration/test_fee_accrual_service.py +++ b/backend/tests/integration/test_fee_accrual_service.py @@ -1,13 +1,5 @@ -"""`FeeAccrualService`/`HighWaterMarkService` against real PostgreSQL (S10 §4/§8/§9): - -- the deposit-vs-gain property test (S10 §8 edge case 2) -- the single most important test in this - sub-project, run with a **nonzero** fee rate so a passing result proves the high-water-mark - mechanism itself excludes deposits, not merely that `FEE_RATE_PCT` happens to be `0.0` today. -- the accrual-and-high-water-mark-update-in-one-transaction guarantee (kill mid-way, assert neither - persisted -- matching S3's own hold-release transactional test pattern). -- `fee_accrual`'s `UNIQUE (customer_id, accrual_date)` idempotency (S10 §8 edge case 4): a second - full run for an already-accrued date is a clean no-op, not an error. -""" +"""`FeeAccrualService`/`HighWaterMarkService` against real Postgres: deposit-vs-gain property, +same-transaction accrual/HWM guarantee, and accrual idempotency (S10 §4/§8/§9).""" from __future__ import annotations @@ -126,9 +118,8 @@ def _post_flow( def test_pure_deposits_with_zero_market_movement_accrue_exactly_zero_fee( db_committing, deposit_amounts: list[Decimal] ) -> None: - """A cash-only account (no market exposure at all) that only ever receives deposits must - accrue **exactly zero** fee, every single day, under a real, nonzero fee rate -- proving the - high-water-mark tracks TWR-adjusted value, never raw portfolio value (S10 §8 edge case 2).""" + """A cash-only account receiving only deposits accrues exactly zero fee under a nonzero + rate (S10 §8 edge case 2).""" customer_id = insert_customer(db_committing) db_committing.add(CustomerCashLock(customer_id=customer_id)) accounts = _cash_accounts(db_committing, customer_id) @@ -148,7 +139,7 @@ def test_pure_deposits_with_zero_market_movement_accrue_exactly_zero_fee( with _fees_uow(db_committing, customer_id=customer_id) as uow: service = FeeAccrualService(uow, fee_rate_pct=Decimal("0.20")) # deliberately nonzero check_date = date(2026, 9, 1) - last_day = day + timedelta(days=3) # a few days past the last deposit too + last_day = day + timedelta(days=3) # a few days past the last deposit while check_date <= last_day: accrual = service.accrue_for_customer(customer_id, check_date) if accrual is not None: @@ -159,9 +150,7 @@ def test_pure_deposits_with_zero_market_movement_accrue_exactly_zero_fee( def test_genuine_market_gain_above_the_peak_accrues_a_real_fee(db_committing) -> None: - """The mirror-image sanity check: a real, positive TWR return above the prior peak *does* - accrue a nonzero fee -- the property test above would be meaningless if this side were also - always zero.""" + """Mirror check: a real gain above the prior peak accrues a nonzero fee.""" customer_id = insert_customer(db_committing) db_committing.add(CustomerCashLock(customer_id=customer_id)) security = Security(symbol="AAPL", name="Apple Inc.", asset_class=SecurityAssetClass.EQUITY) @@ -226,10 +215,7 @@ def test_genuine_market_gain_above_the_peak_accrues_a_real_fee(db_committing) -> def test_killing_the_transaction_midway_persists_neither_the_accrual_nor_the_hwm_update( db_committing, monkeypatch: pytest.MonkeyPatch ) -> None: - """S10 §4/§9's hardest integration test: the high-water-mark ratchet happens *inside* the same - `SAVEPOINT` as the `fee_accrual` insert (`FeeAccrualService.accrue_for_customer`), so an - unexpected failure partway through the posting rolls both back together -- never a ratcheted - peak sitting next to a missing accrual row.""" + """S10 §4/§9: HWM ratchet and fee_accrual insert share one SAVEPOINT and roll back together.""" customer_id = insert_customer(db_committing) db_committing.add(CustomerCashLock(customer_id=customer_id)) security = Security(symbol="AAPL", name="Apple Inc.", asset_class=SecurityAssetClass.EQUITY) @@ -261,8 +247,7 @@ def test_killing_the_transaction_midway_persists_neither_the_accrual_nor_the_hwm PostingLeg(account_id=accounts["cash"].id, amount_money=Money("-10000.00")), ], ) - # Real market appreciation -- $100 -> $110/share -- so day 2's shadow-NAV genuinely exceeds - # day 1's peak, giving the ratchet real work to do. + # $100 -> $110/share so day 2's shadow-NAV exceeds day 1's peak. db_committing.add( DailyClose( security_id=security.id, market_date=day1, close_price=Price("100.00"), @@ -313,8 +298,8 @@ def _raise(*args: object, **kwargs: object) -> None: .all() ) assert hwm is not None - assert hwm.peak_value == Money("10000.00") # unchanged -- the ratchet rolled back - assert accruals == [] # the fee_accrual insert itself never landed + assert hwm.peak_value == Money("10000.00") # unchanged -- ratchet rolled back + assert accruals == [] # insert never landed # --- S10 §8 edge case 4: job-level idempotency ---------------------------------------------------- diff --git a/backend/tests/integration/test_fee_charge_schema.py b/backend/tests/integration/test_fee_charge_schema.py index 217524e..cd7a964 100644 --- a/backend/tests/integration/test_fee_charge_schema.py +++ b/backend/tests/integration/test_fee_charge_schema.py @@ -1,7 +1,5 @@ -"""PostgreSQL-only invariants for S10's `fee_charge` table (S10 §3.4/§9, FR-47): RLS, and -`as_published_watermark`'s DB-level immutability once set -- "attempt an UPDATE, assert it's -rejected at the DB level," per the spec's own required test. -""" +"""`fee_charge` DB-level invariants: RLS and `as_published_watermark` immutability once set +(S10 §3.4/§9, FR-47).""" from __future__ import annotations @@ -24,10 +22,7 @@ def fee_charge_tables(owner_engine): for table in FEE_CHARGE_TABLES: table.create(bind=owner_engine, checkfirst=True) yield - # CASCADE, not a plain drop: `dunning_state`/`fee_accrual` (also S10's own tables) may already - # exist for real via `alembic upgrade head` having been run against this database by another - # concurrent session, with a live FK into `fee_charge` this fixture's own subset doesn't know - # about -- CASCADE removes just that dependent constraint, never a table outside S10's schema. + # CASCADE: other S10 tables may hold a live FK into `fee_charge` outside this fixture's subset. with owner_engine.begin() as connection: for table in reversed(FEE_CHARGE_TABLES): connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) @@ -73,9 +68,7 @@ def test_watermark_update_is_rejected_once_already_set(db_committing) -> None: def test_updating_an_unrelated_column_is_still_permitted(db_committing) -> None: - """The trigger only rejects a *changed* watermark once set -- every other column (status, - stripe_charge_id, journal_entry_id) keeps updating normally as the charge's lifecycle - progresses (S10 §5).""" + """The trigger only rejects a changed watermark; other columns keep updating (S10 §5).""" customer_id = insert_customer(db_committing) charge = _charge(customer_id, watermark=datetime(2026, 9, 1, tzinfo=UTC)) db_committing.add(charge) @@ -91,10 +84,8 @@ def test_updating_an_unrelated_column_is_still_permitted(db_committing) -> None: def test_a_second_charge_for_the_same_customer_and_period_is_rejected(db_committing) -> None: - """F5 (S0 §10.1 audit): `uq_fee_charge_customer_period` is the DB-level backstop behind - `FeeChargeService.create_pending_charge`'s own read-then-insert idempotency check, which two - concurrent or retried `MonthlyFeeChargeJob` runs could otherwise race past -- mirroring - `fee_accrual`'s own `uq_fee_accrual_customer_date` for the identical shape of problem.""" + """F5 (S0 §10.1 audit): `uq_fee_charge_customer_period` backstops the read-then-insert + idempotency check against a concurrent/retried job run.""" customer_id = insert_customer(db_committing) db_committing.add(_charge(customer_id)) db_committing.commit() @@ -121,8 +112,7 @@ def test_a_charge_for_a_different_period_is_still_permitted(db_committing) -> No def test_rewriting_the_watermark_to_the_same_value_is_permitted(db_committing) -> None: - """The trigger compares with `IS DISTINCT FROM` -- a no-op write (the same watermark value - written again) is not a mutation attempt and must not be rejected.""" + """`IS DISTINCT FROM`: rewriting the same watermark value is not a mutation attempt.""" customer_id = insert_customer(db_committing) watermark = datetime(2026, 9, 1, tzinfo=UTC) charge = _charge(customer_id, watermark=watermark) diff --git a/backend/tests/integration/test_fee_restatement_disclosure.py b/backend/tests/integration/test_fee_restatement_disclosure.py index b9466b6..dc8e728 100644 --- a/backend/tests/integration/test_fee_restatement_disclosure.py +++ b/backend/tests/integration/test_fee_restatement_disclosure.py @@ -1,8 +1,5 @@ -"""`RestatementService`'s S10 hook (§6, FR-47): a restatement landing on a period that already has -a `succeeded` `fee_charge` inserts a `fee_restatement_disclosure` row, and never reopens or adjusts -the charge itself. Builds a real, self-consistent ledger + published snapshot first (so -`cross_check` trivially holds), then calls `restate()` and asserts the hook fired. -""" +"""`RestatementService`'s S10 hook: a restatement on an already-charged period inserts a +`fee_restatement_disclosure` row without reopening the charge (§6, FR-47).""" from __future__ import annotations @@ -142,16 +139,14 @@ def test_restatement_touching_an_already_charged_period_inserts_a_disclosure( assert len(disclosures) == 1 assert disclosures[0].fee_charge_id == fee_charge.id - # `_fees_uow`'s own `UnitOfWork.__exit__` closes the shared session, detaching `fee_charge` - # from `db_committing`'s identity map -- a fresh query, not `refresh()` on the stale reference. + # Fresh query, not refresh(): `_fees_uow`'s exit detaches `fee_charge` from the identity map. reloaded_charge = db_committing.query(FeeCharge).filter_by(id=fee_charge.id).one() assert reloaded_charge.status is FeeChargeStatus.SUCCEEDED # never reopened (FR-47) assert reloaded_charge.total_accrued == Money("10.00") # never adjusted def test_restatement_with_no_disclosure_checker_configured_does_not_raise(db_committing) -> None: - """Every existing trigger site (`WashSaleService`, `CorporateActionService`) constructs - `RestatementService(self._uow)` with no checker at all -- must keep working unchanged.""" + """Existing trigger sites construct `RestatementService` with no checker; must keep working.""" customer_id = insert_customer(db_committing) db_committing.add(CustomerCashLock(customer_id=customer_id)) accounts = { diff --git a/backend/tests/integration/test_holds_provider.py b/backend/tests/integration/test_holds_provider.py index 32b23b3..5856393 100644 --- a/backend/tests/integration/test_holds_provider.py +++ b/backend/tests/integration/test_holds_provider.py @@ -6,6 +6,7 @@ from datetime import UTC, datetime import pytest +from sqlalchemy import text from app.core.db import DbRole from app.core.money import Money, Units @@ -29,8 +30,9 @@ def order_tables(owner_engine): for table in ORDER_TABLES: table.create(bind=owner_engine, checkfirst=True) yield - for table in reversed(ORDER_TABLES): - table.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + for table in reversed(ORDER_TABLES): + connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) pytestmark = pytest.mark.usefixtures("order_tables") @@ -150,8 +152,7 @@ def test_open_buy_commitments_values_the_unfilled_remainder_at_the_average_fill_ with _owner_uow() as uow: commitments = OrderHoldsProvider(uow).open_buy_commitments(customer_id) - # 6 units remaining, valued at the realized $100 average fill price -- not the stale $1000 - # (=10 * $100 reference) hold estimate. + # 6 units remaining at the realized $100 fill price, not the stale $1000 hold estimate. assert commitments == Money("600.00") diff --git a/backend/tests/integration/test_idempotency_key_rls.py b/backend/tests/integration/test_idempotency_key_rls.py index 09c76c3..483881d 100644 --- a/backend/tests/integration/test_idempotency_key_rls.py +++ b/backend/tests/integration/test_idempotency_key_rls.py @@ -1,9 +1,5 @@ -"""Row-Level Security on `idempotency_key` (I9, S0 §7.3 audit finding) -- this table caches a -customer's own request/response bodies (financial PII: order/funding responses) and is -tenant-scoped by `customer_id`, but was the only such table in the schema with no RLS policy at -all. Matches `test_ledger_rls.py`'s own established pattern for `posting`, the identical shape of -problem (a denormalized, non-native `customer_id`). -""" +"""Row-Level Security on `idempotency_key`, the only tenant-scoped table with no RLS policy +(I9, S0 §7.3 audit finding).""" from __future__ import annotations diff --git a/backend/tests/integration/test_identity_rls.py b/backend/tests/integration/test_identity_rls.py index 7608e05..b511f63 100644 --- a/backend/tests/integration/test_identity_rls.py +++ b/backend/tests/integration/test_identity_rls.py @@ -1,18 +1,6 @@ -"""Row-Level Security on `customer` (S0 §7.3, ADR 15, ADR 17) — the two required tests, and only -both together are sufficient: - -1. A `customer`-role session cannot read another customer's row, **even with the application-layer - guard disabled** — proving the database is the real control, not `BaseRepository`'s filter. -2. An `adviser`-role session *can* read across customers under the same policy — proving the - role-aware branch actually works, not just the restrictive one (the gap ADR 17 closed after the - original single-customer-only policy would have silently blocked FR-31's own screen). - -Both queries below go through the **`app` role's own credential** (`DbRole.APP`, no BYPASSRLS — -`app_engine`/`test_settings.sqlalchemy_url`) and bypass `SqlCustomerRepository` entirely, issuing a -raw `select(Customer)` directly against `uow.session` — this is "the application-layer guard -disabled" from S0 §7.3's required-test wording: nothing but Postgres itself is left to enforce -tenant isolation for this query. -""" +"""Row-Level Security on `customer`: a customer session can't read another customer's row even +with the app-layer guard bypassed, and adviser/admin sessions can read across customers under the +same policy (S0 §7.3, ADR 15, ADR 17).""" from __future__ import annotations @@ -20,7 +8,7 @@ from typing import TYPE_CHECKING import pytest -from sqlalchemy import select +from sqlalchemy import select, text from app.core.uow import SessionRole, UnitOfWork from app.extensions import DbRole, dispose_engines, init_engines @@ -37,7 +25,7 @@ @pytest.fixture(autouse=True) def engines(test_settings: Settings) -> None: - """`UnitOfWork`'s default session_factory path needs the engine registry populated.""" + """Populates the engine registry `UnitOfWork`'s default session_factory needs.""" init_engines(test_settings) yield None dispose_engines() @@ -45,20 +33,15 @@ def engines(test_settings: Settings) -> None: @pytest.fixture(autouse=True) def customer_table(owner_engine: Engine) -> Iterator[None]: - """Self-sufficient per-file table setup, matching `tests/integration/test_ops_spine.py`'s - `ops_tables` fixture — this file's whole point is proving RLS actually filters, so the table - must exist *with* its policy, not merely exist. `Customer.__table__`'s own `after_create`/ - `before_drop` DDL events (`app/models/identity/customer.py`) enable RLS and create/drop the - `tenant_isolation` policy automatically; nothing here needs to duplicate that SQL. - """ + """Table create/drop fires `Customer.__table__`'s own RLS-policy DDL events.""" Customer.__table__.create(bind=owner_engine, checkfirst=True) yield None - Customer.__table__.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + connection.execute(text(f'DROP TABLE IF EXISTS "{Customer.__table__.name}" CASCADE')) def _insert_two_customers(db_committing: Session) -> tuple[uuid.UUID, uuid.UUID]: - """Owner-role insert — RLS does not constrain the schema owner, so this is pure setup, not - part of what either test below is proving.""" + """Owner-role insert; pure setup, since RLS does not constrain the schema owner.""" customer_a = Customer(email=f"a-{uuid.uuid4()}@trueup.test", password_hash="hash-a") customer_b = Customer(email=f"b-{uuid.uuid4()}@trueup.test", password_hash="hash-b") db_committing.add_all([customer_a, customer_b]) @@ -74,10 +57,8 @@ def test_customer_session_cannot_see_another_customers_row_even_without_the_app_ with UnitOfWork( customer_id=customer_a_id, role=SessionRole.CUSTOMER, db_role=DbRole.APP ) as uow: - # No SqlCustomerRepository, no _tenant_scoped() filter — a raw query under the `app` - # credential. If RLS were not doing the filtering, this would return customer_b too. - # `visible_ids` is read inside the block: `UnitOfWork.__exit__` rolls back (nothing was - # committed) and closes the session, which expires and detaches these ORM instances. + # Raw query under the `app` credential, no repository filter -- read inside the block + # since `UnitOfWork.__exit__` rolls back and detaches these ORM instances. visible_ids = {row.id for row in uow.session.execute(select(Customer)).scalars().all()} assert visible_ids == {customer_a_id} assert customer_b_id not in visible_ids @@ -95,9 +76,7 @@ def test_adviser_session_can_read_across_customers_under_the_same_rls_policy( def test_admin_session_can_also_read_across_customers(db_committing: Session) -> None: - """`admin` is the other branch of `current_setting('app.role') IN ('adviser', 'admin')` — - covered separately since a policy bug scoped to only one of the two role literals would - otherwise pass the adviser test above.""" + """Covers the `admin` branch separately so a bug scoped to one role literal doesn't slip by.""" customer_a_id, customer_b_id = _insert_two_customers(db_committing) with UnitOfWork(customer_id=None, role=SessionRole.ADMIN, db_role=DbRole.APP) as uow: diff --git a/backend/tests/integration/test_kyc_session.py b/backend/tests/integration/test_kyc_session.py index 2da5c3d..c9da0f4 100644 --- a/backend/tests/integration/test_kyc_session.py +++ b/backend/tests/integration/test_kyc_session.py @@ -9,7 +9,7 @@ from datetime import UTC, datetime import pytest -from sqlalchemy import Engine, select +from sqlalchemy import Engine, select, text from sqlalchemy.exc import DBAPIError from app.config import Settings @@ -38,8 +38,9 @@ def _kyc_session_tables(owner_engine: Engine) -> Iterator[None]: Customer.__table__.create(bind=owner_engine, checkfirst=True) KycSession.__table__.create(bind=owner_engine, checkfirst=True) yield None - KycSession.__table__.drop(bind=owner_engine, checkfirst=True) - Customer.__table__.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + connection.execute(text(f'DROP TABLE IF EXISTS "{KycSession.__table__.name}" CASCADE')) + connection.execute(text(f'DROP TABLE IF EXISTS "{Customer.__table__.name}" CASCADE')) def _insert_customer(db_committing) -> uuid.UUID: diff --git a/backend/tests/integration/test_ledger_append_only.py b/backend/tests/integration/test_ledger_append_only.py index 5d5f148..662e521 100644 --- a/backend/tests/integration/test_ledger_append_only.py +++ b/backend/tests/integration/test_ledger_append_only.py @@ -1,14 +1,5 @@ -"""S1 §7 item 3 -- append-only. - -Two layers: `UPDATE`/`DELETE` against `journal_entry`/`posting` fail at the database layer for the -web app's own credential (the revoked grants, S1 §6) -- proven under `DbRole.APP`'s real -`trueup_app` connection, not the schema owner, since a grant revocation means nothing tested -against a role the revocation was never applied to. Separately, a correction round-trip -(`superseded_by` chain, via `PostingService.correct()`) leaves the original row byte-for-byte -unchanged, proving the *only* supported "correction" path never touches the row it corrects (see -`app/models/ledger/journal_entry.py`'s module docstring for why the link points the direction it -does). -""" +"""S1 §7 item 3 append-only: `UPDATE`/`DELETE` fail under `DbRole.APP`'s revoked grants (S1 §6), +and a correction round-trip leaves the original row byte-for-byte unchanged.""" from __future__ import annotations @@ -156,6 +147,6 @@ def test_correction_round_trip_leaves_the_original_row_byte_for_byte_unchanged( after = {c.name: getattr(reloaded_original, c.name) for c in JournalEntry.__table__.columns} assert after == before - assert after["superseded_by"] is None # the original itself was never touched - assert correction.superseded_by == original.id # the *new* row carries the link + assert after["superseded_by"] is None # original never touched + assert correction.superseded_by == original.id # new row carries the link assert correction.entry_type == original.entry_type == JournalEntryType.DEPOSIT diff --git a/backend/tests/integration/test_ledger_balance.py b/backend/tests/integration/test_ledger_balance.py index 9e1c737..57bff40 100644 --- a/backend/tests/integration/test_ledger_balance.py +++ b/backend/tests/integration/test_ledger_balance.py @@ -1,11 +1,5 @@ -"""S1 §7 item 1 -- the money-sum-to-zero invariant (§3.4, ADR 17). - -Two layers, each with its own test: `PostingService` rejects an unbalanced entry before it ever -reaches the database (app-level, `db_session` is enough); the `ledger_balance` deferred constraint -trigger rejects one that bypasses `PostingService` entirely, and it does so **at COMMIT**, not at -flush -- a `db_session`-only test would never exercise this at all (nothing ever commits under -that fixture), so this must run under `db_committing` per `tests/conftest.py`'s own docstring. -""" +"""S1 §7 item 1: the money-sum-to-zero invariant, both at the app layer (`PostingService`) and +the DB's deferred `ledger_balance` trigger at COMMIT (§3.4, ADR 17).""" from __future__ import annotations @@ -52,8 +46,7 @@ def _open_accounts(session, customer_id): class _FakeLedgerUow: - """Just enough of `LedgerUnitOfWork`'s surface for `PostingService` -- a plain `Session` - plumbed through directly, since these tests exercise the trigger/model layer, not RLS.""" + """Just enough of `LedgerUnitOfWork`'s surface for `PostingService`.""" def __init__(self, session): self.session = session @@ -92,8 +85,7 @@ def test_posting_service_rejects_an_unbalanced_entry_before_it_reaches_the_datab def test_ledger_balance_trigger_fires_at_commit_not_at_flush(db_committing) -> None: - """The exact trap S1 §7 item 1 warns about: this must prove the *database*, not - `PostingService`, rejects an out-of-balance entry, and it must prove that happens at COMMIT.""" + """S1 §7 item 1: the database itself rejects an out-of-balance entry, at COMMIT.""" customer_id = insert_customer(db_committing) event_id = insert_inbound_event(db_committing) accounts = _open_accounts(db_committing, customer_id) @@ -106,8 +98,7 @@ def test_ledger_balance_trigger_fires_at_commit_not_at_flush(db_committing) -> N db_committing.add(entry) db_committing.flush() - # Deliberately unbalanced: +1000 cash, -999 customer_equity. Inserted directly -- no - # PostingService involved, so nothing but the database can catch this. + # Deliberately unbalanced, inserted directly -- no PostingService involved. db_committing.add( Posting( journal_entry_id=entry.id, @@ -122,7 +113,7 @@ def test_ledger_balance_trigger_fires_at_commit_not_at_flush(db_committing) -> N amount_money=Money("-999.00"), ) ) - db_committing.flush() # must NOT raise -- the trigger is deferred to COMMIT, not per-insert. + db_committing.flush() # must NOT raise -- trigger is deferred to COMMIT. with pytest.raises((IntegrityError, DBAPIError)): db_committing.commit() @@ -185,16 +176,8 @@ def test_balanced_entries_from_the_spec_commit_cleanly(db_committing, build_legs def test_arbitrary_valid_entries_always_sum_to_zero_and_commit( db_committing, other_amounts: list[Decimal] ) -> None: - """S1 §7 item 1's literal requirement: "property-based test posting arbitrary valid entries; - assert the invariant on every entry_type example in §3.4" -- the fixed examples above prove - the invariant holds for three handpicked cases; this proves it for an arbitrary money leg - count and arbitrary amounts, not just those three. Every generated example is, by - construction, a valid (balanced) entry: `other_amounts` populate 1-3 of `customer_equity`/ - `position_cost`/`fees_expense` (one leg each, so no account ever carries two legs in one - entry), and `cash` always carries the exact negation of their sum -- so the invariant this - test checks is never "does an arbitrary entry happen to balance" but "does *every* balanced - entry, regardless of leg count or amount, actually commit and sum to exactly zero." - """ + """S1 §7 item 1: property-based -- every balanced entry, any leg count or amount, commits + and sums to exactly zero (§3.4).""" customer_id = insert_customer(db_committing) event_id = insert_inbound_event(db_committing) accounts = _open_accounts(db_committing, customer_id) @@ -217,7 +200,7 @@ def test_arbitrary_valid_entries_always_sum_to_zero_and_commit( source_event_id=event_id, legs=legs, ) - db_committing.commit() # must not raise -- the DB trigger must agree the entry balances + db_committing.commit() # must not raise -- DB trigger must agree the entry balances total = db_committing.execute( select(func.coalesce(func.sum(Posting.amount_money), 0)).where( diff --git a/backend/tests/integration/test_ledger_rls.py b/backend/tests/integration/test_ledger_rls.py index 28e54fa..269a5b9 100644 --- a/backend/tests/integration/test_ledger_rls.py +++ b/backend/tests/integration/test_ledger_rls.py @@ -1,15 +1,5 @@ -"""Row-Level Security on `posting` (S1 §3.3, S0 §7.3, ADR 17) — `posting` needed its own -role-aware policy since its tenant key (`customer_id`) is denormalized rather than native. Both -required tests, matching `tests/integration/test_identity_rls.py`'s own pattern for `customer`: - -1. A `customer`-role session cannot read another customer's postings, **even with the - application-layer guard disabled** (a raw `select(Posting)`, no `PostingRepository` filter) -- - proving the database is the real control. -2. An `adviser`-role session *can* read across customers under the same policy -- proving the - role-aware branch actually works, not just the restrictive one. - -Both go through the `app` role's own credential (`DbRole.APP`, no `BYPASSRLS`). -""" +"""Row-Level Security on `posting`, whose denormalized `customer_id` needs its own role-aware +policy (S1 §3.3, S0 §7.3, ADR 17). Mirrors `test_identity_rls.py`'s pattern for `customer`.""" from __future__ import annotations @@ -102,8 +92,7 @@ def test_adviser_session_can_read_postings_across_customers_under_the_same_rls_p def test_admin_session_can_also_read_across_customers(db_committing) -> None: - """`admin` is the other branch of the `IN ('adviser', 'admin')` check -- covered separately - so a policy bug scoped to only one literal would not otherwise be caught.""" + """Covers the `admin` branch separately so a bug scoped to one literal isn't missed.""" customer_a_id, customer_b_id = _insert_two_customers_with_postings(db_committing) with UnitOfWork(customer_id=None, role=SessionRole.ADMIN, db_role=DbRole.APP) as uow: @@ -115,8 +104,7 @@ def test_admin_session_can_also_read_across_customers(db_committing) -> None: def test_customer_session_cannot_see_another_customers_account_row(db_committing) -> None: - """`account`'s own policy (§3.1), same shape -- covered once here since `posting`'s is the - one S1 §3.3 calls out as needing its own denormalization-aware version.""" + """`account`'s own RLS policy (§3.1), same shape, covered once here.""" customer_a_id = insert_customer(db_committing) customer_b_id = insert_customer(db_committing) account_a = Account.create(AccountRole.CASH, customer_id=customer_a_id) diff --git a/backend/tests/integration/test_lot_consumption_service.py b/backend/tests/integration/test_lot_consumption_service.py index 321fd8b..dcea852 100644 --- a/backend/tests/integration/test_lot_consumption_service.py +++ b/backend/tests/integration/test_lot_consumption_service.py @@ -1,12 +1,5 @@ -"""`LotConsumptionService` (S5 §4, ADR 4) -- against real Postgres, since both `record_buy_fill`/ -`record_sell_fill` open/consume lots and post to the ledger in the same transaction. - -S5 §8's own testing strategy names two required cases neither had a dedicated test for before -this file (36% incidental coverage, from one assertion inside an unrelated trade-update-handler -test): "FIFO ordering property test (oldest lot always consumed first absent an override)" and -"the quantity_remaining >= 0 CHECK constraint actually rejects an over-consumption attempt at the -database level, not just in application logic." Found during a full spec/security/quality audit. -""" +"""`LotConsumptionService` against real Postgres: FIFO ordering, specific-lot override, and the +`quantity_remaining >= 0` DB-level CHECK (S5 §4/§8, ADR 4).""" from __future__ import annotations @@ -62,13 +55,12 @@ WashSaleAdjustment.__table__, ] -# All weekdays -- InMemoryTradingCalendar treats every weekday as a trading day, no seeding needed. +# All weekdays -- InMemoryTradingCalendar treats every weekday as a trading day. DAY_1 = datetime(2026, 1, 5, 16, 0, tzinfo=UTC) DAY_2 = datetime(2026, 1, 6, 16, 0, tzinfo=UTC) DAY_3 = datetime(2026, 1, 7, 16, 0, tzinfo=UTC) DAY_4 = datetime(2026, 1, 8, 16, 0, tzinfo=UTC) -# A distinct weekday per lot for the FIFO property test below (up to 4 lots), all strictly -# before the sell on the following Monday. +# A distinct weekday per lot for the FIFO property test below. BUY_DAYS = [ datetime(2026, 1, 5, 16, 0, tzinfo=UTC), datetime(2026, 1, 6, 16, 0, tzinfo=UTC), @@ -110,10 +102,8 @@ def _insert_customer_with_cash(uow: LotsUnitOfWork) -> uuid.UUID: def _insert_security(uow: LotsUnitOfWork) -> uuid.UUID: - # A fresh symbol per call, not a fixed "AAPL": the Hypothesis-driven test below invokes this - # helper multiple times within one test function run (each `@given` example commits for - # real, rather than rolling back), so a fixed symbol would collide on `uq_security_symbol` - # from the second example onward. + # Fresh symbol per call: Hypothesis examples commit for real, so a fixed symbol would + # collide on `uq_security_symbol` from the second example onward. security = Security( symbol=f"TST{uuid.uuid4().hex[:8]}", name="Test Co", asset_class=SecurityAssetClass.EQUITY ) @@ -130,9 +120,7 @@ def _record_fill_order_event( uow: LotsUnitOfWork, *, customer_id: uuid.UUID, security_id: uuid.UUID, execution_id: str, quantity: Units, ) -> None: - """`TaxLot.opening_fill_execution_id` FKs to `order_event.execution_id` -- in production - `AlpacaTradeUpdateHandler` creates this row before calling `record_buy_fill`; standing in for - that caller here.""" + """Standing in for the order/order_event row `AlpacaTradeUpdateHandler` creates.""" order = Order( customer_id=customer_id, security_id=security_id, side=OrderSide.BUY, quantity_requested=quantity, status=OrderStatus.FILLED, filled_quantity=quantity, @@ -170,8 +158,7 @@ def _sell( quantity: Units, price: Price, filled_at: datetime, designated_lot_ids: list[uuid.UUID] | None = None, ) -> list[LotConsumption]: - """`LotConsumption.closing_fill_execution_id` FKs to `order_event.execution_id` too -- - the same real-caller stand-in as `_buy`.""" + """Same real-caller stand-in as `_buy`, for `LotConsumption.closing_fill_execution_id`.""" _record_fill_order_event( uow, customer_id=customer_id, security_id=security_id, execution_id=execution_id, quantity=quantity, @@ -292,9 +279,7 @@ def test_record_sell_fill_spans_multiple_lots_in_fifo_order() -> None: def test_fifo_always_consumes_lots_in_acquisition_order( lot_quantities: list[int], sell_fraction: int ) -> None: - """S5 §8's literal requirement: "oldest lot always consumed first absent an override" -- - property-checked over an arbitrary number of lots and an arbitrary partial sell size, not - just the two fixed-shape examples above.""" + """S5 §8: FIFO holds over an arbitrary number of lots and partial sell size.""" with _owner_uow() as uow: customer_id = _insert_customer_with_cash(uow) security_id = _insert_security(uow) @@ -306,9 +291,7 @@ def test_fifo_always_consumes_lots_in_acquisition_order( service, uow, customer_id=customer_id, security_id=security_id, execution_id=f"exec-{uuid.uuid4()}-{i}", - # A distinct acquisition day per lot -- lock_open_fifo orders by - # (acquired_at, id), so lots sharing one date would make "oldest first" ambiguous - # (id is random), not a property of FIFO ordering itself. + # Distinct acquisition day per lot: a shared date makes "oldest first" ambiguous. quantity=Units(str(quantity)), price=Price("10.00"), filled_at=BUY_DAYS[i], ) lots_oldest_first.append(lot) @@ -316,8 +299,7 @@ def test_fifo_always_consumes_lots_in_acquisition_order( total_units = sum(lot_quantities) sell_quantity = max(1, (total_units * sell_fraction) // 100) - # Never try to sell more than exists across all lots. - sell_quantity = min(sell_quantity, total_units) + sell_quantity = min(sell_quantity, total_units) # never exceed what exists consumptions = _sell( service, uow, customer_id=customer_id, security_id=security_id, @@ -326,9 +308,7 @@ def test_fifo_always_consumes_lots_in_acquisition_order( ) uow.commit() - # The sequence of lots actually touched, in the order fold() consumed them, must be a - # prefix of the acquisition order -- never a newer lot touched before an older one with - # remaining quantity. + # Touched lots must be a prefix of the acquisition order. touched_lot_ids = [c.tax_lot_id for c in consumptions] expected_prefix = [lot.id for lot in lots_oldest_first][: len(touched_lot_ids)] assert touched_lot_ids == expected_prefix @@ -354,7 +334,7 @@ def test_record_sell_fill_honours_a_specific_lot_designation_over_fifo_order() - quantity=Units("10"), price=Price("50.00"), filled_at=DAY_2, ) - # Explicitly designates the *newer* (otherwise-second) lot -- FIFO would pick `older`. + # Explicitly designates the newer lot; FIFO would pick `older`. consumptions = _sell( service, uow, customer_id=customer_id, security_id=security_id, execution_id="exec-sell", quantity=Units("5"), price=Price("150.00"), filled_at=DAY_3, @@ -434,8 +414,7 @@ def test_record_sell_fill_raises_when_quantity_exceeds_every_open_lot() -> None: def test_quantity_remaining_check_constraint_rejects_a_negative_value_at_the_db_level() -> None: - """S5 §8's integration-level requirement: the CHECK itself, independent of - InsufficientLotsError -- a direct write that bypasses the service entirely must still fail.""" + """S5 §8: the DB CHECK itself rejects this, independent of `InsufficientLotsError`.""" with _owner_uow() as uow: customer_id = _insert_customer_with_cash(uow) security_id = _insert_security(uow) diff --git a/backend/tests/integration/test_money_row_delete_grants.py b/backend/tests/integration/test_money_row_delete_grants.py index ccad667..a32820a 100644 --- a/backend/tests/integration/test_money_row_delete_grants.py +++ b/backend/tests/integration/test_money_row_delete_grants.py @@ -1,14 +1,6 @@ -"""F12/I3 (S0 §10.1 audit) -- DB-level DELETE (and, for `wash_sale_adjustment`, UPDATE) revocation -on six tables the S3/S5/S10 migrations shipped with no REVOKE at all, unlike every other -money-bearing table in the schema: `tax_lot`, `lot_consumption`, `wash_sale_adjustment`, -`approval_hold`, `high_water_mark`, `fee_charge`. - -Matches `test_ledger_append_only.py`'s own established pattern exactly: a real `DbRole.APP` -connection (the revocation means nothing tested against the schema owner), and no real row is -needed -- Postgres checks table-level privilege before evaluating a DELETE's WHERE clause, so a -`DELETE ... WHERE id = ` against a real table still raises `permission denied` for a -revoked role even though zero rows would ever match. -""" +"""F12/I3 (S0 §10.1 audit): DB-level DELETE/UPDATE revocation on six money-bearing tables that +shipped with no REVOKE (`tax_lot`, `lot_consumption`, `wash_sale_adjustment`, `approval_hold`, +`high_water_mark`, `fee_charge`).""" from __future__ import annotations @@ -61,7 +53,7 @@ def _tables(owner_engine: Engine) -> Iterator[None]: def _cannot_delete(table_name: str) -> None: - # table_name is always one of this module's own hardcoded literals below, never user input. + # table_name is always a hardcoded literal, never user input. statement = text(f'DELETE FROM "{table_name}" WHERE id = :id') # noqa: S608 with ( UnitOfWork(customer_id=None, role=SessionRole.ADMIN, db_role=DbRole.APP) as uow, diff --git a/backend/tests/integration/test_ops_spine.py b/backend/tests/integration/test_ops_spine.py index 180ded2..f4469e6 100644 --- a/backend/tests/integration/test_ops_spine.py +++ b/backend/tests/integration/test_ops_spine.py @@ -7,6 +7,7 @@ from typing import TYPE_CHECKING import pytest +from sqlalchemy import text from sqlalchemy.exc import IntegrityError from app.core.db import DbRole @@ -43,17 +44,14 @@ def ops_tables(owner_engine: Engine): JobOutbox.__table__, JobRun.__table__, ] - # Per-table `.create()`/`.drop()`, not `Base.metadata.create_all(tables=[...])`: the latter - # still dispatches MetaData-level before_create/after_drop events for *every* native-Postgres - # -enum column anywhere in the shared `Base.metadata` regardless of the `tables=` filter (a - # documented SQLAlchemy behaviour) — now that `app.models.identity`'s `Customer`/`Staff` enums - # share this metadata, that tries to `DROP TYPE kycstatus` while `customer` still exists and - # fails with `DependentObjectsStillExist`. Table-scoped DDL avoids that dispatch entirely. + # Per-table create/drop, not `create_all(tables=[...])`: the latter dispatches enum DDL + # events for the whole shared metadata regardless of the `tables=` filter. for table in tables: table.create(bind=owner_engine, checkfirst=True) yield - for table in reversed(tables): - table.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + for table in reversed(tables): + connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) def _worker_uow() -> OpsUnitOfWork: @@ -89,8 +87,7 @@ def test_skip_locked_prevents_a_second_worker_from_claiming_the_same_row(ops_tab uow.outbox.enqueue("process_inbound_event", {"inbound_event_id": str(uuid.uuid4())}) uow.commit() - # next_attempt_at server-defaults to the real now() at insert time; a hardcoded "now" earlier - # in the same day would wrongly fail claim_next's `next_attempt_at <= now` filter. + # next_attempt_at server-defaults to real now(); a hardcoded "now" would fail claim_next. now = datetime.now(UTC) with _worker_uow() as first_uow: first = JobOutboxRepository(first_uow).claim_next(worker_id="first", now=now) diff --git a/backend/tests/integration/test_order_projection_and_holds.py b/backend/tests/integration/test_order_projection_and_holds.py index bc3ca49..57f6fc1 100644 --- a/backend/tests/integration/test_order_projection_and_holds.py +++ b/backend/tests/integration/test_order_projection_and_holds.py @@ -1,7 +1,5 @@ -"""`ApprovalHoldService`/`OrderProjectionService` against real PostgreSQL (S3 §4/§7/§8): -idempotent release (case 5), and the hardest test in §8 -- a terminal event and its hold release -commit or roll back together, never one without the other (FR-38). -""" +"""`ApprovalHoldService`/`OrderProjectionService` against real Postgres: idempotent release +(case 5) and same-transaction terminal-event/hold-release rollback (S3 §4/§7/§8, FR-38).""" from __future__ import annotations @@ -9,6 +7,7 @@ from datetime import UTC, datetime import pytest +from sqlalchemy import text from app.core.db import DbRole from app.core.money import Money, Units @@ -35,8 +34,9 @@ def order_tables(owner_engine): for table in ORDER_TABLES: table.create(bind=owner_engine, checkfirst=True) yield - for table in reversed(ORDER_TABLES): - table.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + for table in reversed(ORDER_TABLES): + connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) pytestmark = pytest.mark.usefixtures("order_tables") @@ -88,7 +88,7 @@ def test_release_is_idempotent_for_an_order_with_no_active_hold() -> None: uow.commit() with _owner_uow() as uow: - # No hold exists at all (order was below threshold) -- must not raise. + # No hold exists (order was below threshold) -- must not raise. ApprovalHoldService(uow).release( order_id, ApprovalHoldReleaseReason.REJECTED, released_at=NOW ) @@ -114,7 +114,7 @@ def test_release_twice_is_a_no_op_the_second_time() -> None: first_released_at = hold.released_at with _owner_uow() as uow: - # Second release, different reason -- idempotent no-op, must not overwrite the first. + # Second release, different reason: idempotent no-op, must not overwrite. later = datetime(2027, 1, 1, tzinfo=UTC) ApprovalHoldService(uow).release( order_id, ApprovalHoldReleaseReason.CANCELED, released_at=later @@ -181,9 +181,7 @@ def test_submitted_event_releases_the_hold_in_the_same_transaction() -> None: def test_killing_the_transaction_midway_persists_neither_the_event_nor_the_release() -> None: - """S3 §8's hardest integration test: a terminal event and its hold release commit or roll - back together. Simulates a mid-way kill by raising inside the `with` block before `commit()` - -- `UnitOfWork.__exit__` rolls back on any exception, never a partial commit.""" + """S3 §8: a terminal event and its hold release commit or roll back together.""" with _owner_uow() as uow: customer_id = insert_customer(uow.session) uow.commit() @@ -207,7 +205,7 @@ class _SimulatedKillError(Exception): recorded_at=NOW, ), ) - raise _SimulatedKillError # the mid-way kill -- neither write has committed yet + raise _SimulatedKillError # neither write has committed yet with _owner_uow() as uow: order = uow.orders.get_by_id(order_id) @@ -215,10 +213,10 @@ class _SimulatedKillError(Exception): events = uow.order_events.list_for_order(order_id) assert order is not None - assert order.status is OrderStatus.APPROVED # unchanged -- projection update rolled back + assert order.status is OrderStatus.APPROVED # unchanged -- rolled back assert hold is not None - assert hold.status is ApprovalHoldStatus.ACTIVE # unchanged -- release rolled back - assert events == [] # the order_event insert itself rolled back too + assert hold.status is ApprovalHoldStatus.ACTIVE # unchanged -- rolled back + assert events == [] # insert rolled back too def test_successful_commit_persists_both_the_event_and_the_release_together() -> None: diff --git a/backend/tests/integration/test_order_service.py b/backend/tests/integration/test_order_service.py index 2669b00..2f021c7 100644 --- a/backend/tests/integration/test_order_service.py +++ b/backend/tests/integration/test_order_service.py @@ -1,6 +1,5 @@ -"""`OrderService` (S3 §4/§6/§7) against real PostgreSQL: the approval-threshold boundary (case 6), -the customer-approval transition, broker submission (with a fake `BrokerPort`), and case 2's -re-check-before-submission gate.""" +"""`OrderService` against real Postgres: approval threshold (case 6), broker submission, and +case 2's re-check-before-submission gate (S3 §4/§6/§7).""" from __future__ import annotations @@ -8,6 +7,7 @@ from datetime import UTC, date, datetime import pytest +from sqlalchemy import text from app.core.db import DbRole from app.core.money import Money, Price, Units @@ -47,8 +47,9 @@ def order_tables(owner_engine): for table in ORDER_TABLES: table.create(bind=owner_engine, checkfirst=True) yield - for table in reversed(ORDER_TABLES): - table.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + for table in reversed(ORDER_TABLES): + connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) pytestmark = pytest.mark.usefixtures("order_tables") @@ -65,9 +66,8 @@ def _insert_eligible_customer( account_approval_status: AccountApprovalStatus = AccountApprovalStatus.approved, cash: Money = DEFAULT_TEST_CASH, ) -> uuid.UUID: - """`cash` seeds a settled deposit large enough that `OrderService`'s investable-cash check - (S0 §10.1) never blocks this file's state-machine assertions -- pass `Money("0.00")` for a - test that specifically exercises that check.""" + """`cash` seeds a settled deposit large enough to not trip the investable-cash check + (S0 §10.1); pass `Money("0.00")` to exercise that check specifically.""" customer = Customer( email=f"{uuid.uuid4()}@trueup.test", password_hash="hash", @@ -173,8 +173,7 @@ def test_create_order_rejects_a_buy_exceeding_investable_cash() -> None: def test_create_order_allows_a_sell_with_zero_investable_cash() -> None: - """A sell has no cash precondition (module docstring) -- only KYC/account-approval and, at - fill time, an actual lot to sell from.""" + """A sell has no cash precondition -- only KYC/account-approval, and a lot at fill time.""" with _owner_uow() as uow: customer_id = _insert_eligible_customer(uow, cash=Money("0.00")) order = _service(uow).create_order( diff --git a/backend/tests/integration/test_orders_schema.py b/backend/tests/integration/test_orders_schema.py index 07e0b3a..621fb40 100644 --- a/backend/tests/integration/test_orders_schema.py +++ b/backend/tests/integration/test_orders_schema.py @@ -1,7 +1,5 @@ -"""PostgreSQL-only invariants for S3's schema: RLS on `order`/`approval_hold` (S0 §7.3, ADR 17), -append-only enforcement on `order_event` (ADR 7), and the unique constraints §3's dedupe/one-hold- -per-order guarantees depend on. -""" +"""S3 schema DB invariants: RLS on `order`/`approval_hold` (S0 §7.3, ADR 17), append-only on +`order_event` (ADR 7), and dedupe/one-hold-per-order unique constraints.""" from __future__ import annotations @@ -9,7 +7,7 @@ from datetime import UTC, datetime import pytest -from sqlalchemy import select +from sqlalchemy import select, text from sqlalchemy.exc import DBAPIError, IntegrityError from app.core.db import DbRole @@ -28,8 +26,9 @@ def order_tables(owner_engine): for table in ORDER_TABLES: table.create(bind=owner_engine, checkfirst=True) yield - for table in reversed(ORDER_TABLES): - table.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + for table in reversed(ORDER_TABLES): + connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) pytestmark = pytest.mark.usefixtures("order_tables") @@ -171,8 +170,7 @@ def test_order_event_seq_is_unique_per_order(db_committing) -> None: def test_order_event_execution_id_is_globally_unique(db_committing) -> None: - """ADR 7's dedupe key -- a replayed fill webhook's `execution_id` collides regardless of - which order it names.""" + """ADR 7: a replayed fill webhook's `execution_id` collides regardless of order.""" customer_id = insert_customer(db_committing) order = _order(customer_id) db_committing.add(order) diff --git a/backend/tests/integration/test_posting_trigger.py b/backend/tests/integration/test_posting_trigger.py index 6070a74..98ca336 100644 --- a/backend/tests/integration/test_posting_trigger.py +++ b/backend/tests/integration/test_posting_trigger.py @@ -1,11 +1,5 @@ -"""S1 §7 item 2 -- units never cross into money. - -Three layers: the `CHECK` constraint rejects a posting with both (or neither) column set; the -`posting_before_insert` trigger rejects a posting whose non-null column disagrees with its -account's dimension; and separately, the trigger sets `posting.customer_id` from the target -account regardless of what the insert statement supplied -- proving the trigger, not the caller, -is the source of truth (S1 §3.3). -""" +"""S1 §7 item 2: units never cross into money. CHECK constraint, dimension-mismatch trigger, +and `posting.customer_id` set from the target account (S1 §3.3).""" from __future__ import annotations @@ -37,11 +31,7 @@ def _open_entry(session, customer_id) -> uuid.UUID: def test_check_rejects_a_posting_with_both_columns_set(db_session) -> None: - """Whichever leg the target account's dimension doesn't match, `posting_before_insert` (§3.3) - raises first -- so this is rejected before the `CHECK` even gets a chance to run, same as the - "wrong dimension" tests below. Either way, the row is rejected at the database, which is what - this test proves; `ProgrammingError` (the trigger) and `IntegrityError` (the `CHECK`) are both - acceptable outcomes.""" + """Rejected at the database either way; the trigger or the CHECK, both acceptable.""" customer_id = insert_customer(db_session) cash = Account.create(AccountRole.CASH, customer_id=customer_id) db_session.add(cash) @@ -108,8 +98,7 @@ def test_trigger_rejects_money_posted_against_a_units_account(db_session) -> Non def test_trigger_sets_customer_id_from_the_account_regardless_of_what_the_insert_supplied( db_session, ) -> None: - """The trigger, not the caller, is the source of truth (S1 §3.3): even a deliberately wrong - `customer_id` supplied on the insert is overwritten from the target account.""" + """S1 §3.3: the trigger overwrites even a deliberately wrong supplied `customer_id`.""" customer_id = insert_customer(db_session) wrong_customer_id = insert_customer(db_session) cash = Account.create(AccountRole.CASH, customer_id=customer_id) diff --git a/backend/tests/integration/test_rebalance_flow.py b/backend/tests/integration/test_rebalance_flow.py index 025529d..a1bda84 100644 --- a/backend/tests/integration/test_rebalance_flow.py +++ b/backend/tests/integration/test_rebalance_flow.py @@ -1,7 +1,5 @@ -"""A full `DriftEvaluationService` + `RebalanceOrderService` run against a seeded model and -holdings (S9 §9), against real PostgreSQL -- the real `OrderService`/`CashPolicyService`, not -fakes, so this proves the actual DB-backed wiring `MonthlyRebalanceJob` uses end to end. -""" +"""A full `DriftEvaluationService` + `RebalanceOrderService` run against real Postgres, with the +real `OrderService`/`CashPolicyService` wiring `MonthlyRebalanceJob` uses (S9 §9).""" from __future__ import annotations @@ -10,6 +8,7 @@ from decimal import Decimal import pytest +from sqlalchemy import text from app.core.db import DbRole from app.core.money import Money, Price, Units @@ -63,8 +62,9 @@ def rebalance_flow_tables(owner_engine): for table in REBALANCE_FLOW_TABLES: table.create(bind=owner_engine, checkfirst=True) yield - for table in reversed(REBALANCE_FLOW_TABLES): - table.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + for table in reversed(REBALANCE_FLOW_TABLES): + connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) pytestmark = pytest.mark.usefixtures("rebalance_flow_tables") @@ -75,9 +75,7 @@ def _owner_uow() -> RebalanceUnitOfWork: def _seed_scenario(uow: RebalanceUnitOfWork) -> tuple[uuid.UUID, uuid.UUID, uuid.UUID]: - """A customer with $50,000 cash, 80 shares of `over_security` (@$100 = $8,000), and no - holding of `under_security` at all -- assigned to a model targeting 10%/90% of the two, - so the first is over-weight (a sell) and the second under-weight (a first-time buy).""" + """$50,000 cash, 80 shares of `over_security`, no `under_security`; model targets 10%/90%.""" customer = Customer( email=f"{uuid.uuid4()}@trueup.test", password_hash="hash", @@ -239,11 +237,7 @@ def test_evaluate_raises_for_a_customer_with_no_assigned_model() -> None: def test_evaluate_returns_no_flags_when_everything_is_exactly_on_target() -> None: - """S9 §8 item 3: the fully-quiescent case -- every holding, including the implicit CASH - holding, exactly matches its target, so nothing is flagged. `target_weight`'s own sum-to-one - trigger (S9 §3.2) means a model's named securities always claim the full 100% -- cash's own - implicit target is therefore always exactly 0 in this schema, never "typically 0"; landing on - it here means the customer is fully invested with no idle cash left over.""" + """S9 §8 item 3: every holding, including implicit CASH, exactly matches its target.""" with _owner_uow() as uow: customer = Customer( email=f"{uuid.uuid4()}@trueup.test", diff --git a/backend/tests/integration/test_reconciliation_service.py b/backend/tests/integration/test_reconciliation_service.py index 3036d36..e1fce21 100644 --- a/backend/tests/integration/test_reconciliation_service.py +++ b/backend/tests/integration/test_reconciliation_service.py @@ -1,13 +1,5 @@ """`ReconciliationService` (S7 §6), `BreakAgingService` (S7 §7), and `ReconciliationBreak`'s -FR-44 `CHECK` constraint -- against real Postgres, since the three matching loops read live -ledger state and the constraint is a database-level guarantee. - -No test file anywhere in this codebase covered any of S7 before this one (0% coverage on both -reconciliation_service.py and internal_state.py) -- found during a full spec/security/quality -audit. S7 §11's own testing strategy specifically names the FR-32 live-fire scenario (tamper one -position, assert exactly one break with the correct customer/security/expected/actual) and the -resolved_by CHECK as required cases. -""" +FR-44 CHECK constraint, against real Postgres.""" from __future__ import annotations @@ -52,8 +44,8 @@ ReconciliationBreak.__table__, ] -MARKET_DATE = date(2026, 1, 5) # a Monday -- a real trading day per InMemoryTradingCalendar -HOLIDAY_DATE = date(2026, 1, 3) # a Saturday -- weekends are never trading days +MARKET_DATE = date(2026, 1, 5) # a Monday, a real trading day +HOLIDAY_DATE = date(2026, 1, 3) # a Saturday, never a trading day @pytest.fixture @@ -99,16 +91,8 @@ def _post_position( security_id: uuid.UUID, quantity: Units, ) -> None: - """A units-only entry (S1 §3.4's own worked example) is enough to establish a position for - `read_internal_positions`'s purposes -- no money legs required to balance since the zero-sum - check only sums `amount_money` legs. - - Uses `CORRECTION`, deliberately *not* `TRADE_BUY` -- `CUSTODIAN_OBSERVABLE_ENTRY_TYPES` - (`internal_state.py`) would make a `TRADE_BUY` entry also register as an internal transaction - the transactions loop expects a file match for, coupling a position-only test's fixture setup - to the transactions loop it is not testing. `CORRECTION` is documented as exactly this kind of - internal-only bookkeeping act with no independent custodian-side transaction id. - """ + """Units-only `CORRECTION` entry: establishes a position without also registering as an + internal transaction the transactions loop would expect a file match for.""" units_account = Account.create( AccountRole.POSITION_UNITS, customer_id=customer_id, security_id=security_id ) @@ -126,8 +110,7 @@ def _post_position( def _post_settled_deposit( uow: ReconciliationUnitOfWork, *, customer_id: uuid.UUID, amount: Money ) -> None: - """Same `CORRECTION`-not-`DEPOSIT` reasoning as `_post_position` -- isolates a cash-only - test's fixture setup from the transactions loop.""" + """Same `CORRECTION`-not-`DEPOSIT` reasoning as `_post_position`, isolating the cash case.""" cash_account = Account.create(AccountRole.CASH, customer_id=customer_id) equity_account = Account.create(AccountRole.CUSTOMER_EQUITY, customer_id=customer_id) uow.session.add_all([cash_account, equity_account]) @@ -147,9 +130,7 @@ def _post_settled_deposit( def _post_observable_transaction( uow: ReconciliationUnitOfWork, *, customer_id: uuid.UUID, amount: Money, source_event_id: str ) -> None: - """A DEPOSIT entry (a `CUSTODIAN_OBSERVABLE_ENTRY_TYPES` member) traceable back to a specific - `source_event_id` -- the exact key `read_internal_transactions`/`_match_transactions` join - on.""" + """A DEPOSIT entry traceable to a `source_event_id`, the join key the transactions loop uses.""" cash_account = Account.create(AccountRole.CASH, customer_id=customer_id) equity_account = Account.create(AccountRole.CUSTOMER_EQUITY, customer_id=customer_id) uow.session.add_all([cash_account, equity_account]) @@ -211,9 +192,7 @@ def test_positions_matching_the_file_open_no_break() -> None: def test_fr32_live_fire_a_single_tampered_position_opens_exactly_one_correct_break() -> None: - """S7 §11's named required test: generate a clean baseline, tamper exactly one position, - assert exactly one reconciliation_break opens identifying the correct customer/security/ - expected/actual values.""" + """S7 §11 (FR-32): tamper one position; exactly one break opens with correct expected/actual.""" with _owner_uow() as uow: customer_id = insert_customer(uow.session) security_id = _insert_security(uow) @@ -247,8 +226,7 @@ def test_fr32_live_fire_a_single_tampered_position_opens_exactly_one_correct_bre def test_a_position_present_only_in_the_file_is_a_break() -> None: - """S7 §6: the union of both sides -- a position the file reports but Trueup has never heard - of is a mismatch (internal treated as 0), not silently ignored.""" + """S7 §6: a position the file reports but Trueup never heard of is a mismatch, not ignored.""" with _owner_uow() as uow: customer_id = insert_customer(uow.session) security_id = _insert_security(uow) @@ -337,8 +315,7 @@ def test_cash_mismatch_opens_a_break_with_both_values() -> None: def test_a_matched_transaction_opens_no_break() -> None: - """A real deposit is both a cash fact and a transaction fact -- the file set below matches - both, exactly what a genuinely clean custodian file would report for this same deposit.""" + """A real deposit is both a cash fact and a transaction fact; the file set matches both.""" with _owner_uow() as uow: customer_id = insert_customer(uow.session) _post_observable_transaction( @@ -374,8 +351,7 @@ def test_a_matched_transaction_opens_no_break() -> None: def test_a_custodian_transaction_with_no_internal_match_is_a_break() -> None: - """S7 §9's inject_late_dividend shape: a file transaction with no corresponding S1 entry - yet.""" + """S7 §9's inject_late_dividend shape: a file transaction with no corresponding S1 entry yet.""" with _owner_uow() as uow: customer_id = insert_customer(uow.session) @@ -407,9 +383,7 @@ def test_a_custodian_transaction_with_no_internal_match_is_a_break() -> None: def test_an_internal_transaction_with_no_custodian_match_is_a_break() -> None: - """Isolates the transactions loop: the file's cash total already agrees (matching what the - deposit produced), but the transaction line itself is missing -- only the transactions loop - should flag anything.""" + """Isolates the transactions loop: cash total agrees, but the transaction line is missing.""" with _owner_uow() as uow: customer_id = insert_customer(uow.session) _post_observable_transaction( @@ -515,7 +489,7 @@ def test_resolved_status_requires_a_non_null_resolved_by_at_the_db_level(db_comm db_committing.add(break_row) db_committing.commit() - break_row.status = ReconciliationBreakStatus.RESOLVED # resolved_by left null -- must fail + break_row.status = ReconciliationBreakStatus.RESOLVED # resolved_by left null, must fail with pytest.raises((IntegrityError, DBAPIError)): db_committing.commit() diff --git a/backend/tests/integration/test_repository.py b/backend/tests/integration/test_repository.py index 2b5ef40..92b9b2f 100644 --- a/backend/tests/integration/test_repository.py +++ b/backend/tests/integration/test_repository.py @@ -11,7 +11,7 @@ from typing import TYPE_CHECKING, Protocol import pytest -from sqlalchemy import DateTime, String, select +from sqlalchemy import DateTime, String, select, text from sqlalchemy.dialects import postgresql from sqlalchemy.orm import Mapped, mapped_column @@ -31,15 +31,14 @@ @pytest.fixture(autouse=True) def engines(test_settings: Settings) -> None: - """`UnitOfWork`'s default session_factory path needs the engine registry populated — every - test in this file constructs a `UnitOfWork` directly, so this applies to all of them.""" + """Populates the engine registry `UnitOfWork`'s default session_factory needs.""" init_engines(test_settings) yield None dispose_engines() class Widget(Base): - """Throwaway bitemporal, tenant-scoped entity — exists only for this test module.""" + """Throwaway bitemporal, tenant-scoped entity for this test module.""" __tablename__ = "repo_test_widget" @@ -70,16 +69,12 @@ def __init__(self, uow: UnitOfWork) -> None: @pytest.fixture def widget_table(owner_engine: Engine): - # `Widget.__table__.create()/.drop()` directly, not `Base.metadata.create_all(tables=[...])`: - # the latter still dispatches MetaData-level before_create/after_drop events for *every* - # native-Postgres-enum column anywhere in the shared `Base.metadata` (a documented SQLAlchemy - # behaviour, not scoped by the `tables=` filter), which — now that `app.models.identity`'s - # `Customer`/`Staff` enums share this metadata — tries to `DROP TYPE kycstatus` while - # `customer` still exists and fails with `DependentObjectsStillExist`. Table-scoped DDL avoids - # that dispatch entirely and is exactly what a throwaway single-table fixture needs anyway. + # Table-scoped create/drop, not `create_all(tables=[...])`: the latter dispatches enum DDL + # events for the whole shared metadata regardless of the `tables=` filter. Widget.__table__.create(bind=owner_engine, checkfirst=True) yield - Widget.__table__.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + connection.execute(text(f'DROP TABLE IF EXISTS "{Widget.__table__.name}" CASCADE')) T0 = datetime(2026, 9, 1, 12, 0, 0, tzinfo=UTC) @@ -145,8 +140,7 @@ def test_find_as_of_respects_the_watermark(widget_table: None) -> None: def test_find_as_of_requires_the_keyword_argument(widget_table: None) -> None: - """Omitting `as_of` is a `TypeError`, caught by `mypy --strict` before this even runs — this - proves the runtime half of ADR 6's discipline too.""" + """Omitting `as_of` is a `TypeError` at runtime too, per ADR 6.""" customer_id = uuid.uuid4() with _customer_uow(customer_id) as uow: repo = WidgetRepository(uow) @@ -215,7 +209,7 @@ def find_as_of(self, *, as_of: Watermark) -> Sequence[Widget]: ... class _FakeWidgetRepository: - """An in-memory fake — no database, no `UnitOfWork` — substituted purely by shape.""" + """In-memory fake substituted purely by shape, no database or `UnitOfWork`.""" def __init__(self, widgets: Sequence[Widget]) -> None: self._widgets = widgets @@ -225,7 +219,7 @@ def find_as_of(self, *, as_of: Watermark) -> Sequence[Widget]: def _labels_visible(repo: WidgetRepositoryProtocol, *, as_of: Watermark) -> set[str]: - """Stands in for a service method: depends on the Protocol, not on `BaseRepository`.""" + """Stands in for a service method, depending on the Protocol, not `BaseRepository`.""" return {widget.label for widget in repo.find_as_of(as_of=as_of)} diff --git a/backend/tests/integration/test_settlement_obligation.py b/backend/tests/integration/test_settlement_obligation.py index 585c506..8e69dac 100644 --- a/backend/tests/integration/test_settlement_obligation.py +++ b/backend/tests/integration/test_settlement_obligation.py @@ -1,12 +1,5 @@ -"""S1 §7 item 4 -- settlement never mutates the ledger. - -`settlement_obligation` is the one table S1 allows to mutate at all (§6: "a state machine, not a -ledger"), and only in one controlled way: `pending` -> a terminal state, exactly once. This module -proves both halves: transitioning to `confirmed` writes zero new `posting` rows (ADR 2 -- no -physical transfer of money internally on confirmation), and a second transition attempt against an -already-terminal row is rejected by the database trigger, not just by -`SettlementObligationRepository`'s own guard. -""" +"""S1 §7 item 4: settlement never mutates the ledger. `confirmed` writes zero new postings +(ADR 2); a second transition off a terminal row is rejected by both app and DB trigger (S1 §6).""" from __future__ import annotations @@ -98,9 +91,7 @@ def test_repository_rejects_a_second_transition_on_an_already_terminal_obligatio def test_database_trigger_rejects_a_second_transition_even_bypassing_the_repository( db_committing, ) -> None: - """The repository's own guard is application-level; this proves the *database* also rejects - it, via `settlement_obligation_before_update` (S1 §6) -- the same "trigger, not just the - service" split S1 §7 requires throughout.""" + """The database itself also rejects this, via `settlement_obligation_before_update` (S1 §6).""" customer_id = insert_customer(db_committing) obligation = _open_obligation(db_committing, customer_id) obligation.status = SettlementObligationStatus.CONFIRMED diff --git a/backend/tests/integration/test_target_weight_sum.py b/backend/tests/integration/test_target_weight_sum.py index c5ff87a..1c02609 100644 --- a/backend/tests/integration/test_target_weight_sum.py +++ b/backend/tests/integration/test_target_weight_sum.py @@ -1,13 +1,12 @@ -"""S9 §3.2's cross-row sum-to-one invariant on `target_weight` -- a deferred constraint trigger, -tested the same way S1's ledger-balance trigger is tested -(`tests/integration/test_ledger_balance.py`): a deliberately unbalanced model definition must -fail at `COMMIT`, not at flush, so this runs under `db_committing` (S9 §9).""" +"""S9 §3.2's cross-row sum-to-one invariant on `target_weight`: a deferred trigger that fails at +COMMIT, not flush (S9 §9).""" from __future__ import annotations from decimal import Decimal import pytest +from sqlalchemy import text from sqlalchemy.exc import DBAPIError, IntegrityError from app.models.marketdata.security import Security, SecurityAssetClass @@ -22,8 +21,9 @@ def rebalance_model_tables(owner_engine): for table in REBALANCE_MODEL_TABLES: table.create(bind=owner_engine, checkfirst=True) yield - for table in reversed(REBALANCE_MODEL_TABLES): - table.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + for table in reversed(REBALANCE_MODEL_TABLES): + connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) pytestmark = pytest.mark.usefixtures("rebalance_model_tables") @@ -42,8 +42,7 @@ def _seed_model_and_securities(session): def test_target_weight_sum_to_one_trigger_fires_at_commit_not_at_flush(db_committing) -> None: model, security_one, security_two = _seed_model_and_securities(db_committing) - # Deliberately unbalanced: 0.60 + 0.30 = 0.90, not 1.0. Inserted directly, matching - # test_ledger_balance.py's own pattern of bypassing any application-layer service. + # Deliberately unbalanced: 0.60 + 0.30 = 0.90, not 1.0. db_committing.add( TargetWeight( model_portfolio_id=model.id, security_id=security_one.id, weight_pct=Decimal("0.60") @@ -54,7 +53,7 @@ def test_target_weight_sum_to_one_trigger_fires_at_commit_not_at_flush(db_commit model_portfolio_id=model.id, security_id=security_two.id, weight_pct=Decimal("0.30") ) ) - db_committing.flush() # must NOT raise -- the trigger is deferred to COMMIT. + db_committing.flush() # must NOT raise -- trigger is deferred to COMMIT. with pytest.raises((IntegrityError, DBAPIError)): db_committing.commit() @@ -78,9 +77,7 @@ def test_a_balanced_model_commits_cleanly(db_committing) -> None: def test_deleting_a_weight_without_replacing_it_reopens_the_violation(db_committing) -> None: - """S9 §3.2: a model portfolio with any target weights at all must sum to 1.0 -- removing a - row without a replacement in the same transaction is exactly as invalid as never having - balanced (this module's own docstring).""" + """S9 §3.2: removing a row without a replacement is as invalid as never having balanced.""" model, security_one, security_two = _seed_model_and_securities(db_committing) db_committing.add( TargetWeight( diff --git a/backend/tests/integration/test_twr_service.py b/backend/tests/integration/test_twr_service.py index d60e51e..45d22ff 100644 --- a/backend/tests/integration/test_twr_service.py +++ b/backend/tests/integration/test_twr_service.py @@ -1,7 +1,5 @@ -"""`TwrService.compute_twr` (S4 §5, ADR 3) — sub-period breaks, FR-17's flow-timing invariance, -and the restatement-composability property (S4 §5/§9: a corrected close touches exactly one -stored sub-period row). -""" +"""`TwrService.compute_twr`: sub-period breaks, flow-timing invariance (FR-17), and +restatement-composability (S4 §5/§9, ADR 3).""" from __future__ import annotations @@ -167,8 +165,7 @@ def test_zero_positions_and_no_flows_is_zero_percent(db_committing) -> None: def test_first_sub_period_return_is_zero_by_construction(db_committing) -> None: - """S4 §8 case 3: `v_begin` is the deposit that opened the account -- `value_book(v_begin)` - already reflects it, so the first sub-period's return is zero even though money moved.""" + """S4 §8 case 3: `value_book(v_begin)` reflects the opening deposit, so return is zero.""" customer_id = insert_customer(db_committing) db_committing.add(CustomerCashLock(customer_id=customer_id)) security = _security(db_committing) @@ -228,9 +225,7 @@ def test_two_same_day_flows_produce_one_sub_period_break_not_two(db_committing) def test_a_deposit_mid_period_does_not_pollute_the_return(db_committing) -> None: - """FR-17: the market grows from $1000 to $1100 (10%) in the first sub-period, then a $500 - deposit lands, then the market is flat -- the linked TWR must be 10%, not diluted or inflated - by the deposit itself.""" + """FR-17: a 10% gain then a mid-period deposit must link to a 10% TWR, not diluted/inflated.""" customer_id = insert_customer(db_committing) db_committing.add(CustomerCashLock(customer_id=customer_id)) security = _security(db_committing) @@ -278,8 +273,7 @@ def test_a_deposit_mid_period_does_not_pollute_the_return(db_committing) -> None def test_partial_valuation_flags_the_sub_period_provisional(db_committing) -> None: - """S4 §8 case 4: a sub-period whose `v_end` lands on a day with no confirmed close is - provisional, not silently treated as complete.""" + """S4 §8 case 4: a sub-period whose `v_end` has no confirmed close is provisional.""" customer_id = insert_customer(db_committing) db_committing.add(CustomerCashLock(customer_id=customer_id)) security = _security(db_committing) @@ -301,7 +295,7 @@ def test_partial_valuation_flags_the_sub_period_provisional(db_committing) -> No _close( db_committing, security_id=security.id, market_date=date(2026, 9, 1), price=Price("100.00") ) - # No close for 2026-09-10 -- the period's end lands on a missing valuation. + # No close for 2026-09-10: the period's end lands on a missing valuation. db_committing.commit() with _valuation_uow(db_committing, customer_id=customer_id) as uow: @@ -313,8 +307,7 @@ def test_partial_valuation_flags_the_sub_period_provisional(db_committing) -> No def test_a_corrected_close_re_links_only_the_affected_sub_period(db_committing) -> None: - """S4 §5/§9: a corrected close for one day re-links exactly that sub-period; every other - stored `sub_period_return` row is byte-for-byte unchanged (same id, same recorded_at).""" + """S4 §5/§9: a corrected close re-links only its sub-period; every other row is unchanged.""" customer_id = insert_customer(db_committing) db_committing.add(CustomerCashLock(customer_id=customer_id)) security = _security(db_committing) @@ -358,7 +351,7 @@ def test_a_corrected_close_re_links_only_the_affected_sub_period(db_committing) first_sub_period = (first.sub_periods[0].id, first.sub_periods[0].recorded_at) second_sub_period = (first.sub_periods[1].id, first.sub_periods[1].recorded_at) - # A correction to the *second* sub-period's closing price only (2026-09-10), recorded later. + # Correction to the second sub-period's closing price only, recorded later. _close( db_committing, security_id=security.id, market_date=date(2026, 9, 10), price=Price("130.00") ) @@ -374,8 +367,7 @@ def test_a_corrected_close_re_links_only_the_affected_sub_period(db_committing) assert second.sub_periods[1].return_pct != first.sub_periods[1].return_pct assert second.twr != first.twr - # Exactly one row exists for the unaffected sub-period -- the correction never wrote a - # second one, matching "left untouched" literally, not just "recomputed to the same value". + # Exactly one row exists for the unaffected sub-period; the correction never wrote a second. unaffected_rows = ( db_committing.query(SubPeriodReturn) .filter_by( @@ -395,8 +387,7 @@ def test_a_corrected_close_re_links_only_the_affected_sub_period(db_committing) ) @given(flow_offset_days=st.integers(min_value=1, max_value=8)) def test_twr_is_unaffected_by_flow_timing(db_committing, flow_offset_days: int) -> None: - """FR-17, property-based: a cash-only account (no market exposure) has an exact 0% TWR no - matter which day within the period an external flow lands.""" + """FR-17, property-based: a cash-only account has exactly 0% TWR regardless of flow timing.""" customer_id = insert_customer(db_committing) db_committing.add(CustomerCashLock(customer_id=customer_id)) accounts = { diff --git a/backend/tests/integration/test_uow.py b/backend/tests/integration/test_uow.py index c0bd8b6..d104a27 100644 --- a/backend/tests/integration/test_uow.py +++ b/backend/tests/integration/test_uow.py @@ -1,8 +1,5 @@ -"""`UnitOfWork` (S0 §5, ADR 14): the transaction boundary, against real PostgreSQL. - -Real Postgres is required here specifically because the subject of several of these tests is -`SET LOCAL`/`set_config(..., true)` transaction-scoping, which SQLite has no equivalent of at all. -""" +"""`UnitOfWork`'s transaction boundary against real Postgres, including `SET LOCAL`-style +transaction-scoping SQLite has no equivalent of (S0 §5, ADR 14).""" from __future__ import annotations @@ -23,8 +20,7 @@ @pytest.fixture def engines(test_settings: Settings) -> None: - """Populate `app.extensions`'s engine registry so the default (non-injected) session_factory - path — `get_session_factory(db_role)` — is exercised too, not only the test-injection seam.""" + """Populates the engine registry so the default (non-injected) session_factory path runs too.""" init_engines(test_settings) yield None dispose_engines() @@ -32,8 +28,7 @@ def engines(test_settings: Settings) -> None: @pytest.fixture def probe_table(db_committing: Session): - """A throwaway table this test file owns for the life of one test — created and dropped here, - never a real model (those belong to later waves).""" + """Throwaway table for the life of one test; never a real model.""" db_committing.execute(text("CREATE TABLE uow_probe (id serial primary key, note text)")) db_committing.commit() yield "uow_probe" @@ -84,14 +79,13 @@ def test_adviser_session_does_not_require_a_customer_id(owner_engine: Engine) -> def test_customer_role_without_a_customer_id_is_rejected_immediately() -> None: - """Fail at construction, not at query time — mirrors ADR 6's discipline for `as_of`.""" + """Fails at construction, not query time, mirroring ADR 6's `as_of` discipline.""" with pytest.raises(ValueError, match="customer_id"): UnitOfWork(customer_id=None, role=SessionRole.CUSTOMER) def test_set_local_scope_does_not_survive_the_transaction(owner_engine: Engine) -> None: - """`set_config(..., true)` behaves exactly like `SET LOCAL`: gone once the transaction that set - it ends, even though the underlying physical connection is reused for the next one.""" + """`set_config(..., true)` behaves like `SET LOCAL`: gone once its transaction ends.""" customer_id = uuid.uuid4() connection = owner_engine.connect() session = Session(bind=connection, expire_on_commit=False) @@ -104,8 +98,7 @@ def test_set_local_scope_does_not_survive_the_transaction(owner_engine: Engine) assert _current_setting(uow.session, "app.customer_id") == str(customer_id) uow.commit() - # UnitOfWork.__exit__ closed the session but not the externally-owned connection; reusing - # it here proves the GUC reset at COMMIT, not merely because a new connection was used. + # Reusing the same connection proves the GUC reset at COMMIT, not a new-connection artifact. leaked = _current_setting(session, "app.customer_id") assert leaked in ("", None) session.rollback() @@ -163,7 +156,7 @@ def test_explicit_rollback_discards_the_write( class _BoomError(Exception): - """Stands in for an arbitrary service-level failure.""" + """Stands in for an arbitrary service failure.""" def test_exception_inside_the_block_rolls_back_and_propagates( @@ -206,8 +199,7 @@ def test_default_db_role_is_app() -> None: class _ProbeUnitOfWork(UnitOfWork): - """Stands in for a wave-owned `LedgerUnitOfWork`/`OrdersUnitOfWork`, proving the documented - extension mechanism actually works end to end.""" + """Stands in for a wave-owned `LedgerUnitOfWork`/`OrdersUnitOfWork`.""" @cached_property def probe(self) -> object: diff --git a/backend/tests/integration/test_valuation_service.py b/backend/tests/integration/test_valuation_service.py index c1c3ef7..8a171e0 100644 --- a/backend/tests/integration/test_valuation_service.py +++ b/backend/tests/integration/test_valuation_service.py @@ -1,9 +1,5 @@ -"""`ValuationService.value_book` (S4 §4, §8 cases 1/5, §9's real-`NUMERIC` rounding rule). - -Real PostgreSQL throughout -- `Price * Units -> Money` must be tested against real `NUMERIC` -columns, not simulated (S4 §9), and `daily_close`'s bitemporal `recorded_at` ordering only actually -means something once rows really persist. -""" +"""`ValuationService.value_book` against real Postgres: `NUMERIC` rounding and `recorded_at` +bitemporal ordering (S4 §4/§8 cases 1/5/§9).""" from __future__ import annotations @@ -44,10 +40,7 @@ def valuation_tables(owner_engine): for table in MARKETDATA_TABLES: table.create(bind=owner_engine, checkfirst=True) yield - # Raw DROP TABLE ... CASCADE, not Table.drop(): `market_data_source` is one Postgres enum - # shared by two tables (daily_close, market_calendar_cache), and SQLAlchemy's per-Table drop - # event tries to drop the enum type alongside whichever of the two tables is dropped first, - # failing with "DependentObjectsStillExist" while the other table still references it. + # Raw DROP TABLE, not Table.drop(): a shared Postgres enum makes per-Table drop events race. with owner_engine.begin() as connection: for table in reversed(MARKETDATA_TABLES): connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}"')) @@ -59,7 +52,7 @@ def valuation_tables(owner_engine): class _LedgerLikeUow: - """`PostingService`'s minimal dependency, matching `test_cash_policy.py`'s own double.""" + """`PostingService`'s minimal dependency.""" def __init__(self, session): self.session = session @@ -162,7 +155,7 @@ def _close( def test_zero_positions_values_the_cash_balance_alone(db_committing) -> None: - """S4 §8 case 1: fully in cash -- value_book returns the cash balance alone, complete.""" + """S4 §8 case 1: fully in cash -- value_book returns the cash balance alone.""" customer_id = insert_customer(db_committing) db_committing.add(CustomerCashLock(customer_id=customer_id)) security = _security(db_committing) @@ -212,8 +205,7 @@ def test_confirmed_close_prices_the_position_with_exact_numeric_rounding(db_comm def test_missing_close_flags_partial_and_omits_the_position(db_committing) -> None: - """S4 §6: no close arrived at all -- inferred by absence, never substituted, whole book - flagged partial.""" + """S4 §6: no close at all -- inferred by absence, whole book flagged partial.""" customer_id = insert_customer(db_committing) db_committing.add(CustomerCashLock(customer_id=customer_id)) security = _security(db_committing) @@ -239,7 +231,7 @@ def test_missing_close_flags_partial_and_omits_the_position(db_committing) -> No def test_stale_only_close_is_treated_the_same_as_missing(db_committing) -> None: - """A `stale`-flagged close never substitutes for a confirmed one (S4 §6).""" + """S4 §6: a `stale`-flagged close never substitutes for a confirmed one.""" customer_id = insert_customer(db_committing) db_committing.add(CustomerCashLock(customer_id=customer_id)) security = _security(db_committing) @@ -271,8 +263,7 @@ def test_stale_only_close_is_treated_the_same_as_missing(db_committing) -> None: def test_a_later_recorded_at_correction_wins_however_many_followed(db_committing) -> None: - """S4 §8 case 5: two corrected closes for the same market_date, in quick succession -- - `value_book` always reads the latest `recorded_at`'s confirmed row.""" + """S4 §8 case 5: `value_book` always reads the latest `recorded_at`'s confirmed row.""" customer_id = insert_customer(db_committing) db_committing.add(CustomerCashLock(customer_id=customer_id)) security = _security(db_committing) diff --git a/backend/tests/integration/test_wash_sale_service.py b/backend/tests/integration/test_wash_sale_service.py index 5aed14e..4d90515 100644 --- a/backend/tests/integration/test_wash_sale_service.py +++ b/backend/tests/integration/test_wash_sale_service.py @@ -1,11 +1,5 @@ -"""`WashSaleService` (S5 §5, ADR 11) -- against real Postgres, since the reactive check joins -`lot_consumption`/`tax_lot`/`wash_sale_adjustment` and posts to the ledger in the same transaction. - -S5 §8's own testing strategy names "wash-sale disallowed-amount arithmetic including the -`min(loss, replacement_basis)` cap" as a required unit-level case; no test anywhere in this -codebase exercised either entry point before this file (46% incidental coverage from other -services' own tests, no dedicated test) -- found during a full spec/security/quality audit. -""" +"""`WashSaleService` against real Postgres: the reactive check and disallowed-amount arithmetic +including the `min(loss, replacement_basis)` cap (S5 §5/§8, ADR 11).""" from __future__ import annotations @@ -204,7 +198,7 @@ def test_on_loss_sale_is_a_no_op_with_no_replacement_in_window() -> None: consumption = _consume( uow, tax_lot=lot, realized_gain_loss=Money("-50.00"), sale_date=date(2026, 2, 1) ) - # No other lot exists at all -- nothing in the +/-30-day window. + # No other lot exists in the +/-30-day window. WashSaleService(uow).on_loss_sale( consumption, customer_id=customer_id, security_id=security_id @@ -219,7 +213,7 @@ def test_on_loss_sale_is_a_no_op_with_no_replacement_in_window() -> None: def test_on_loss_sale_disallows_the_full_loss_when_replacement_basis_is_larger() -> None: - """min(loss, replacement_basis) -- the loss is the binding constraint here.""" + """min(loss, replacement_basis): the loss is the binding constraint here.""" with _owner_uow() as uow: customer_id = _insert_customer(uow) security_id = _insert_security(uow) @@ -231,8 +225,7 @@ def test_on_loss_sale_disallows_the_full_loss_when_replacement_basis_is_larger() uow, tax_lot=original_lot, realized_gain_loss=Money("-100.00"), sale_date=date(2026, 2, 1) ) - # Replacement bought 10 days before the sale, well within the trailing 30-day window, - # with a basis (2000) larger than the loss (100). + # Replacement bought within the trailing 30-day window; basis (2000) > loss (100). replacement_lot = _open_lot( uow, customer_id=customer_id, security_id=security_id, quantity=Units("10"), cost_basis=Money("2000.00"), acquired_at=date(2026, 1, 22), @@ -258,7 +251,7 @@ def test_on_loss_sale_disallows_the_full_loss_when_replacement_basis_is_larger() def test_on_loss_sale_caps_disallowance_at_the_smaller_replacement_basis() -> None: - """min(loss, replacement_basis) -- the replacement's own basis is the binding constraint.""" + """min(loss, replacement_basis): the replacement's basis is the binding constraint.""" with _owner_uow() as uow: customer_id = _insert_customer(uow) security_id = _insert_security(uow) @@ -270,7 +263,7 @@ def test_on_loss_sale_caps_disallowance_at_the_smaller_replacement_basis() -> No uow, tax_lot=original_lot, realized_gain_loss=Money("-500.00"), sale_date=date(2026, 2, 1) ) - # Replacement's own basis (30) is smaller than the loss (500) -- the cap must bind. + # Replacement's basis (30) is smaller than the loss (500); the cap must bind. _open_lot( uow, customer_id=customer_id, security_id=security_id, quantity=Units("1"), cost_basis=Money("30.00"), acquired_at=date(2026, 1, 22), @@ -339,7 +332,7 @@ def test_on_buy_fill_adjusts_an_earlier_loss_sale_in_the_forward_window() -> Non sale_date=date(2026, 2, 1) ) - # The replacement buy arrives *after* the loss sale -- the forward-window side. + # Replacement buy arrives after the loss sale: the forward-window side. new_lot = _open_lot( uow, customer_id=customer_id, security_id=security_id, quantity=Units("10"), cost_basis=Money("2000.00"), acquired_at=date(2026, 2, 10), @@ -365,7 +358,7 @@ def test_on_buy_fill_never_treats_a_lot_as_its_own_replacement() -> None: uow, customer_id=customer_id, security_id=security_id, quantity=Units("10"), cost_basis=Money("1000.00"), acquired_at=date(2026, 1, 1), ) - # A consumption whose tax_lot_id *is* the new lot itself -- must be skipped, not adjusted. + # Consumption's tax_lot_id is the new lot itself; must be skipped, not adjusted. consumption = _consume( uow, tax_lot=lot, realized_gain_loss=Money("-50.00"), sale_date=date(2026, 1, 1) ) diff --git a/backend/tests/integration/test_withdrawal_service.py b/backend/tests/integration/test_withdrawal_service.py index 14fbfc1..ed8e56e 100644 --- a/backend/tests/integration/test_withdrawal_service.py +++ b/backend/tests/integration/test_withdrawal_service.py @@ -8,7 +8,7 @@ from datetime import UTC, datetime import pytest -from sqlalchemy import Engine, select +from sqlalchemy import Engine, select, text from app.config import Settings from app.core.crypto import reset_cipher, set_cipher @@ -62,8 +62,9 @@ def _tables(owner_engine: Engine) -> Iterator[None]: for table in _TABLES: table.create(bind=owner_engine, checkfirst=True) yield None - for table in reversed(_TABLES): - table.drop(bind=owner_engine, checkfirst=True) + with owner_engine.begin() as connection: + for table in reversed(_TABLES): + connection.execute(text(f'DROP TABLE IF EXISTS "{table.name}" CASCADE')) def _customer( diff --git a/backend/tests/unit/test_agent_action_request.py b/backend/tests/unit/test_agent_action_request.py new file mode 100644 index 0000000..3f4f3e6 --- /dev/null +++ b/backend/tests/unit/test_agent_action_request.py @@ -0,0 +1,115 @@ +"""`AgentActionRequestRepository`'s application-layer transition guard (S13 §3.1, ADR 24). Pure: +no database call, no `UnitOfWork` needed.""" + +from __future__ import annotations + +import uuid +from datetime import UTC, datetime + +import pytest + +from app.models.ops.agent_action_request import ( + AgentActionRequest, + AgentActionRequestRepository, + AgentActionStatus, + AgentActionType, + InvalidAgentActionTransitionError, +) + + +def _make_row(status: AgentActionStatus = AgentActionStatus.PENDING) -> AgentActionRequest: + return AgentActionRequest( + action=AgentActionType.KYC_OVERRIDE, + arguments={"customer_id": str(uuid.uuid4()), "reason": "test"}, + requesting_agent="adviser@trueup.test (test token)", + justification="test", + status=status, + ) + + +@pytest.fixture +def repo() -> AgentActionRequestRepository: + return AgentActionRequestRepository(uow=None) # type: ignore[arg-type] + + +def test_approve_from_pending_succeeds(repo: AgentActionRequestRepository) -> None: + row = _make_row() + reviewed_by = uuid.uuid4() + reviewed_at = datetime.now(UTC) + + repo.approve(row, reviewed_by=reviewed_by, reviewed_at=reviewed_at, review_note="looks right") + + assert row.status is AgentActionStatus.APPROVED + assert row.reviewed_by == reviewed_by + assert row.reviewed_at == reviewed_at + assert row.review_note == "looks right" + + +@pytest.mark.parametrize( + "status", + [ + AgentActionStatus.APPROVED, + AgentActionStatus.REJECTED, + AgentActionStatus.EXECUTED, + AgentActionStatus.EXECUTION_FAILED, + ], +) +def test_approve_from_non_pending_raises( + repo: AgentActionRequestRepository, status: AgentActionStatus +) -> None: + row = _make_row(status=status) + + with pytest.raises(InvalidAgentActionTransitionError): + repo.approve(row, reviewed_by=uuid.uuid4(), reviewed_at=datetime.now(UTC), review_note=None) + + +def test_reject_from_pending_succeeds(repo: AgentActionRequestRepository) -> None: + row = _make_row() + reviewed_by = uuid.uuid4() + reviewed_at = datetime.now(UTC) + + repo.reject(row, reviewed_by=reviewed_by, reviewed_at=reviewed_at, review_note="not warranted") + + assert row.status is AgentActionStatus.REJECTED + assert row.reviewed_by == reviewed_by + assert row.review_note == "not warranted" + + +def test_reject_from_non_pending_raises(repo: AgentActionRequestRepository) -> None: + row = _make_row(status=AgentActionStatus.APPROVED) + + with pytest.raises(InvalidAgentActionTransitionError): + repo.reject(row, reviewed_by=uuid.uuid4(), reviewed_at=datetime.now(UTC), review_note="x") + + +def test_mark_executed_from_approved_succeeds(repo: AgentActionRequestRepository) -> None: + row = _make_row(status=AgentActionStatus.APPROVED) + executed_at = datetime.now(UTC) + + repo.mark_executed(row, executed_at=executed_at) + + assert row.status is AgentActionStatus.EXECUTED + assert row.executed_at == executed_at + + +def test_mark_executed_from_pending_raises(repo: AgentActionRequestRepository) -> None: + row = _make_row(status=AgentActionStatus.PENDING) + + with pytest.raises(InvalidAgentActionTransitionError): + repo.mark_executed(row, executed_at=datetime.now(UTC)) + + +def test_mark_execution_failed_from_approved_succeeds(repo: AgentActionRequestRepository) -> None: + row = _make_row(status=AgentActionStatus.APPROVED) + + repo.mark_execution_failed(row, execution_error="reconciliation_break already resolved") + + assert row.status is AgentActionStatus.EXECUTION_FAILED + assert row.execution_error == "reconciliation_break already resolved" + + +def test_mark_execution_failed_from_pending_raises(repo: AgentActionRequestRepository) -> None: + row = _make_row(status=AgentActionStatus.PENDING) + + with pytest.raises(InvalidAgentActionTransitionError): + repo.mark_execution_failed(row, execution_error="x") diff --git a/backend/tests/unit/test_clock.py b/backend/tests/unit/test_clock.py index edfa1a1..1d0fbee 100644 --- a/backend/tests/unit/test_clock.py +++ b/backend/tests/unit/test_clock.py @@ -1,10 +1,5 @@ -"""MarketClock (ADR 12, S0 §10.8): a UTC instant is not "which day is it" until it is converted. - -ADR 12 exists because NY is behind UTC: late evening in New York is already the next calendar day -in UTC. Code that reads `.date()` off a stored UTC instant directly gets that wrong on any evening -instant, and the wrongness silently shifts by an hour whenever US daylight saving flips — which is -why every test below pins a concrete calendar date and checks it across both US DST offsets. -""" +"""`MarketClock`: a UTC instant is not "which day is it" until converted, across both US DST +offsets (ADR 12, S0 §10.8).""" from __future__ import annotations @@ -46,7 +41,7 @@ def test_market_date_rejects_naive_datetime(clock: MarketClock) -> None: def test_market_date_late_utc_instant_still_previous_ny_day_in_winter_est( clock: MarketClock, ) -> None: - """9:30pm EST on Jan 15 is 2:30am UTC on Jan 16 — must still resolve to Jan 15.""" + """9:30pm EST on Jan 15 is 2:30am UTC on Jan 16 -- must resolve to Jan 15.""" instant = datetime(2026, 1, 16, 2, 30, tzinfo=UTC) assert clock.market_date(instant) == date(2026, 1, 15) @@ -54,7 +49,7 @@ def test_market_date_late_utc_instant_still_previous_ny_day_in_winter_est( def test_market_date_late_utc_instant_still_previous_ny_day_in_summer_edt( clock: MarketClock, ) -> None: - """9:30pm EDT on Jul 15 is 1:30am UTC on Jul 16 — must still resolve to Jul 15.""" + """9:30pm EDT on Jul 15 is 1:30am UTC on Jul 16 -- must resolve to Jul 15.""" instant = datetime(2026, 7, 16, 1, 30, tzinfo=UTC) assert clock.market_date(instant) == date(2026, 7, 15) diff --git a/backend/tests/unit/test_config.py b/backend/tests/unit/test_config.py index f9d69fb..3ce6123 100644 --- a/backend/tests/unit/test_config.py +++ b/backend/tests/unit/test_config.py @@ -1,8 +1,4 @@ -"""Settings must fail loudly rather than let the app start insecurely. - -S0 §12: "No secret has a default value in code. A required setting with no value present fails -application startup immediately, rather than running with an insecure fallback (A05)." -""" +"""Settings must fail loudly rather than let the app start insecurely (S0 §12, A05).""" from __future__ import annotations @@ -24,12 +20,8 @@ def build(**overrides: str | None) -> Settings: - """Construct Settings from an explicit environment, ignoring any real .env on disk *and* any - of `COMPLETE`'s own keys already present in the process environment -- `conftest.py`'s - autouse `_default_settings_env` fixture sets exactly these for every other test in the suite - (so controllers calling the module-level `get_settings()` singleton work without a `.env`), - which would otherwise silently satisfy a field this function's caller is deliberately trying - to prove `Settings` requires.""" + """Builds Settings from an explicit environment, clearing any of `COMPLETE`'s keys that + `conftest.py`'s autouse fixture already sets in the process environment.""" env = {**COMPLETE, **overrides} values = {k: v for k, v in env.items() if v is not None} with pytest.MonkeyPatch.context() as mp: @@ -46,7 +38,7 @@ def test_complete_environment_builds_settings() -> None: @pytest.mark.parametrize("missing", sorted(COMPLETE)) def test_every_required_setting_is_required(missing: str) -> None: - """Removing any one required setting must raise, not silently default.""" + """Removing any one required setting must raise, never silently default.""" with pytest.raises(ValidationError) as exc: build(**{missing: None}) assert missing.lower() in str(exc.value).lower() @@ -87,12 +79,7 @@ def test_provider_credentials_are_detected_when_present() -> None: class TestBlankValuesAreTreatedAsUnset: - """`.env.example` ships every optional credential as `KEY=` with no value. - - An empty string is not a credential. Left uncoerced, `AZURE_KEY_VAULT_URL=` reads as - "configured" and the app tries to reach a vault at "", and `ALPACA_API_KEY_ID=` reads as a - real key and the adapter authenticates with nothing. Both fail far from the cause. - """ + """`.env.example` ships optional credentials as `KEY=`; an empty string must not read as set.""" def test_blank_optional_credential_is_none(self) -> None: settings = build(ALPACA_API_KEY_ID="", ALPACA_API_SECRET_KEY=" ") @@ -107,18 +94,18 @@ def test_blank_value_falls_back_to_a_declared_default(self) -> None: assert build(ALPACA_BASE_URL="").alpaca_base_url == "https://paper-api.alpaca.markets" def test_blank_required_setting_still_fails(self) -> None: - """Blank must mean "unset", which for a required setting is an error — not a default.""" + """Blank means "unset", which for a required setting is an error, not a default.""" with pytest.raises(ValidationError): build(SECRET_KEY="") def test_secrets_are_not_exposed_by_repr() -> None: - """Root CLAUDE.md: secrets never reach a log. A settings dump is a log waiting to happen.""" + """Secrets never reach a log; a settings dump is a log waiting to happen.""" rendered = repr(build()) assert "x" * 32 not in rendered assert "pw@localhost" not in rendered def test_sqlalchemy_url_is_returned_as_plain_string() -> None: - """SQLAlchemy needs the raw URL; the SecretStr wrapper must not leak into the DSN.""" + """The SecretStr wrapper must not leak into the DSN SQLAlchemy needs raw.""" assert build().sqlalchemy_url.startswith("postgresql+psycopg://trueup_app:") diff --git a/backend/tests/unit/test_crypto.py b/backend/tests/unit/test_crypto.py index 4ef42d2..48f0ca4 100644 --- a/backend/tests/unit/test_crypto.py +++ b/backend/tests/unit/test_crypto.py @@ -1,8 +1,4 @@ -"""Field-level encryption at rest (ADR 23). - -The envelope layout is identical across every Cipher adapter, so switching from LocalDevCipher to -KeyVaultCipher does not change the stored column format. These tests pin that contract. -""" +"""Field-level encryption at rest: the envelope layout every Cipher adapter must share (ADR 23).""" from __future__ import annotations @@ -45,8 +41,7 @@ def test_round_trip_empty_string(cipher: LocalDevCipher) -> None: def test_same_plaintext_encrypts_differently_each_time(cipher: LocalDevCipher) -> None: - """A fresh data key and nonce per value: identical tokens must not produce identical rows, - or the database leaks which customers share a value.""" + """Fresh data key and nonce per value: identical tokens must not produce identical rows.""" assert cipher.encrypt("same") != cipher.encrypt("same") @@ -121,7 +116,7 @@ def test_none_passes_through(self, cipher: LocalDevCipher) -> None: reset_cipher() def test_unconfigured_cipher_raises_rather_than_storing_plaintext(self) -> None: - """The failure mode for a misconfigured cipher must be a crash, never a plaintext write.""" + """A misconfigured cipher must crash, never write plaintext.""" reset_cipher() with pytest.raises(CipherNotConfiguredError): get_cipher() diff --git a/backend/tests/unit/test_customer.py b/backend/tests/unit/test_customer.py index c3ebe36..7139a91 100644 --- a/backend/tests/unit/test_customer.py +++ b/backend/tests/unit/test_customer.py @@ -1,8 +1,4 @@ -"""`Customer` model invariants (S2 §3.1 / S0 §7.2): the `AuthPrincipal` shape and the enum columns. - -No database — see `test_staff.py`'s module docstring for why the enum-domain assertion is made -against SQLAlchemy's column metadata rather than a live insert. -""" +"""`Customer` model invariants: `AuthPrincipal` shape and enum columns, no database (S2 §3.1).""" from __future__ import annotations @@ -53,10 +49,7 @@ def test_account_approval_status_column_enforces_its_declared_value_set() -> Non def test_kyc_status_and_approval_status_default_to_pending() -> None: - """`default=` is a client-side INSERT-time default (S0 §5) — it applies when the row is - flushed, not on bare construction, so this asserts the column's configured default rather - than an unflushed instance's attribute. - """ + """`default=` is a client-side INSERT-time default (S0 §5); asserts the column config.""" assert Customer.__table__.c.kyc_status.default.arg == KycStatus.pending assert Customer.__table__.c.account_approval_status.default.arg == AccountApprovalStatus.pending diff --git a/backend/tests/unit/test_db.py b/backend/tests/unit/test_db.py index 92d369b..6915fff 100644 --- a/backend/tests/unit/test_db.py +++ b/backend/tests/unit/test_db.py @@ -1,8 +1,5 @@ -"""Database role and session-factory resolution (S0 §7.3, ADR 14). - -Ensures the credential boundary is strictly maintained and that a failure to configure -the process-wide resolver fails loudly rather than falling back to a default connection. -""" +"""Database role and session-factory resolution: credential boundary and loud-fail-if-unconfigured +(S0 §7.3, ADR 14).""" from __future__ import annotations @@ -22,14 +19,14 @@ @pytest.fixture(autouse=True) def _reset_resolver() -> Generator[None, None, None]: - """Ensure tests start and end with a clean global state.""" + """Ensures tests start and end with a clean global state.""" reset_session_factory_resolver() yield reset_session_factory_resolver() class FakeResolver: - """A test double that records which role it was asked to resolve.""" + """Test double that records which role it was asked to resolve.""" def __init__(self) -> None: self.resolved_roles: list[DbRole] = [] diff --git a/backend/tests/unit/test_drift_evaluation_service.py b/backend/tests/unit/test_drift_evaluation_service.py index d3ebe97..85ce0d9 100644 --- a/backend/tests/unit/test_drift_evaluation_service.py +++ b/backend/tests/unit/test_drift_evaluation_service.py @@ -32,7 +32,7 @@ def test_a_holding_exactly_at_target_has_zero_drift() -> None: ], ) def test_exactly_at_the_band_edge_does_not_trigger(current: str) -> None: - """S9 §9's documented boundary: `== band` does not trigger.""" + """S9 §9: `== band` does not trigger.""" assert _flagged(current, "0.20") is False @@ -44,24 +44,21 @@ def test_exactly_at_the_band_edge_does_not_trigger(current: str) -> None: ], ) def test_just_past_the_band_edge_triggers(current: str) -> None: - """`> band` triggers -- the other half of S9 §9's documented boundary.""" + """S9 §9: `> band` triggers.""" assert _flagged(current, "0.20") is True def test_a_wider_target_scales_the_absolute_tolerance() -> None: - """S9 §5: the band is relative to each holding's own target weight, not a flat +/-5 - percentage-point band -- a 40%-target holding's edge is twice as wide in absolute terms as a - 20%-target holding's.""" + """S9 §5: the band is relative to each holding's target weight, not a flat +/-5pp band.""" assert _flagged("0.42", "0.40") is False # +0.05 relative, at the edge assert _flagged("0.421", "0.40") is True # past it def test_a_zero_target_with_a_nonzero_holding_is_always_flagged() -> None: - """S9 §8 item 4: a security dropped from the model has no ratio to take a relative drift - against -- always flagged, a full-exit sell, regardless of how small the holding is.""" + """S9 §8 item 4: a security dropped from the model is always flagged, a full-exit sell.""" assert _flagged("0.0001", "0") is True def test_a_zero_target_with_nothing_held_is_not_flagged() -> None: - """Nothing targeted, nothing held -- genuinely nothing to do.""" + """Nothing targeted, nothing held: nothing to do.""" assert _flagged("0", "0") is False diff --git a/backend/tests/unit/test_dunning_service.py b/backend/tests/unit/test_dunning_service.py index c0422aa..1a1c9ae 100644 --- a/backend/tests/unit/test_dunning_service.py +++ b/backend/tests/unit/test_dunning_service.py @@ -89,8 +89,7 @@ def test_record_retry_failure_schedules_the_next_backoff_below_max_attempts() -> def test_record_retry_failure_exhausts_at_max_attempts() -> None: - """FR-48: exhaustion is a standing, customer-visible balance owed -- `fee_charge.status` - moves to `dunning`, never silently dropped.""" + """FR-48: exhaustion moves `fee_charge.status` to `dunning`, never silently dropped.""" uow = _FakeUow() service = DunningService(uow, max_attempts=3, now=lambda: _FIXED_NOW) # type: ignore[arg-type] charge = _charge() diff --git a/backend/tests/unit/test_errors.py b/backend/tests/unit/test_errors.py index d96c70b..23286c3 100644 --- a/backend/tests/unit/test_errors.py +++ b/backend/tests/unit/test_errors.py @@ -1,9 +1,4 @@ -"""RFC 9457 problem+json error hierarchy (S0 §8). - -The one property every test here protects: whatever an `AppError` is constructed with, the -rendered problem body can never carry more than `{type, title, status, code, correlation_id}` — -no stack trace, no SQL fragment, no internal identifier, no PII. -""" +"""RFC 9457 error hierarchy: rendered body never exceeds the declared key set (S0 §8).""" from __future__ import annotations @@ -72,15 +67,14 @@ def test_correlation_id_is_carried_through_unchanged() -> None: def test_code_can_be_overridden_for_a_stable_domain_code() -> None: - """A later wave raises `ValidationError(code="insufficient_investable_cash")` without a new - class — the status/title stay 422, only the machine-readable branch code changes.""" + """A later wave can override `code` without a new class; status/title stay 422.""" problem = ValidationError(code="insufficient_investable_cash").to_problem("cid-7") assert problem["status"] == 422 assert problem["code"] == "insufficient_investable_cash" def test_sensitive_detail_never_leaks_into_the_rendered_problem() -> None: - """The detail is available to logging, never returned to the client.""" + """Detail is available to logging, never returned to the client.""" sensitive = ( "duplicate key value violates unique constraint on customer_id=11111111-1111-1111-1111-" "111111111111 with plaid_access_token=access-sandbox-super-secret" @@ -98,8 +92,7 @@ def test_sensitive_detail_never_leaks_into_the_rendered_problem() -> None: def test_default_detail_is_the_title_not_none() -> None: - """Raising `NotFoundError()` with no detail should still produce a sensible exception message - for logs, without requiring every call site to repeat the title as a string.""" + """`NotFoundError()` with no detail still produces a sensible exception message for logs.""" error = NotFoundError() assert str(error) == "Not Found" assert error.detail is None diff --git a/backend/tests/unit/test_fake_broker.py b/backend/tests/unit/test_fake_broker.py index 285ced4..2c66013 100644 --- a/backend/tests/unit/test_fake_broker.py +++ b/backend/tests/unit/test_fake_broker.py @@ -1,7 +1,5 @@ -"""`FakeBrokerAdapter` (S3 §8, ADR 22) — submission behaviour, and that its synthesized -`trade_updates` message shapes are accepted by `TradeUpdatesConsumer.handle_message` with no -websocket ever opened. -""" +"""`FakeBrokerAdapter`: submission behavior and synthesized message shapes accepted by +`TradeUpdatesConsumer.handle_message`, no websocket opened (S3 §8, ADR 22).""" from __future__ import annotations diff --git a/backend/tests/unit/test_high_water_mark_service.py b/backend/tests/unit/test_high_water_mark_service.py index 44d032e..00f7e9a 100644 --- a/backend/tests/unit/test_high_water_mark_service.py +++ b/backend/tests/unit/test_high_water_mark_service.py @@ -1,11 +1,5 @@ -"""`HighWaterMarkService.ratchet`/`get_or_create` (S10 §4, ADR 10) — pure logic, no database. - -`shadow_nav` itself needs a real ledger (TWR/valuation), so it is exercised in -`tests/integration/test_fee_accrual_service.py` instead (matching `TwrService`'s own precedent of -keeping its DB-backed property tests in `tests/integration/`); this file isolates the -high-water-mark *ratchet* -- the part of S10's core correctness requirement that is pure arithmetic -over an already-known `shadow_value`. -""" +"""`HighWaterMarkService.ratchet`/`get_or_create`: pure arithmetic over a known `shadow_value`, +no database (S10 §4, ADR 10).""" from __future__ import annotations @@ -49,8 +43,7 @@ def _service() -> HighWaterMarkService: def test_get_or_create_creates_at_first_ever_value_with_zero_gain() -> None: - """S10 §4: "creates at first-ever value if absent" -- the first day always yields zero gain, - since nothing has ever been "above" a peak that did not exist yet.""" + """S10 §4: creates at first-ever value; the first day always yields zero gain.""" service = _service() customer_id = uuid.uuid4() shadow_value = Money("10000.00") @@ -63,20 +56,18 @@ def test_get_or_create_creates_at_first_ever_value_with_zero_gain() -> None: def test_ratchet_never_moves_the_peak_down() -> None: - """The high-water-mark's entire guarantee (S10 §4/ADR 10): a drawdown never lowers the peak, - and accrues nothing until the customer's value exceeds the *prior* peak again.""" + """S10 §4/ADR 10: a drawdown never lowers the peak nor accrues until value exceeds it again.""" service = _service() customer_id = uuid.uuid4() hwm = service.get_or_create(customer_id, shadow_value=Money("10000.00")) service.ratchet(hwm, shadow_value=Money("10000.00")) - # A drawdown to 8000 -- no new high, zero gain, peak stays at 10000. + # Drawdown to 8000: no new high, zero gain, peak stays at 10000. gain_in_drawdown = service.ratchet(hwm, shadow_value=Money("8000.00")) assert gain_in_drawdown == Money("0.00") assert hwm.peak_value == Money("10000.00") - # Recovering only back to the prior peak -- still zero gain (S10 §8 edge case 1: no - # retroactive "catch-up" on the drawdown period). + # Recovering only to the prior peak: still zero gain (S10 §8 edge case 1). gain_at_prior_peak = service.ratchet(hwm, shadow_value=Money("10000.00")) assert gain_at_prior_peak == Money("0.00") assert hwm.peak_value == Money("10000.00") @@ -93,8 +84,7 @@ def test_ratchet_never_moves_the_peak_down() -> None: ) ) def test_peak_is_monotonically_non_decreasing_over_any_sequence(shadow_values: list) -> None: - """Property: whatever sequence of shadow-NAV values arrives, `peak_value` never decreases, - and every reported gain equals the peak's own increase that step.""" + """Property: `peak_value` never decreases; every gain equals the peak's increase that step.""" service = _service() customer_id = uuid.uuid4() first = Money(str(shadow_values[0])) diff --git a/backend/tests/unit/test_kyc_service.py b/backend/tests/unit/test_kyc_service.py index ef606a6..3fa6ed8 100644 --- a/backend/tests/unit/test_kyc_service.py +++ b/backend/tests/unit/test_kyc_service.py @@ -10,7 +10,12 @@ from app.integrations.fake.fake_kyc import FakeKycAdapter from app.models.identity.customer import Customer, KycStatus from app.models.identity.kyc_session import KycSession, KycSessionStatus, SqlKycSessionRepository -from app.services.identity.kyc_service import CustomerNotFoundError, KycLockedError, KycService +from app.services.identity.kyc_service import ( + CustomerNotFoundError, + KycLockedError, + KycPortNotConfiguredError, + KycService, +) MAX_ATTEMPTS = 3 @@ -106,8 +111,7 @@ def test_canceled_verdict_rejects_the_session_and_the_customer() -> None: def test_processing_verdict_stays_pending_and_never_touches_the_customer() -> None: - """ADR 9's explicit warning: a session stuck in `processing` must never be misreported as - `rejected` by a naive "not yet verified = rejected" simplification.""" + """ADR 9: a session stuck in `processing` must never be misreported as `rejected`.""" customer = _customer() uow = _FakeUow(customer) service = _service(uow, FakeKycAdapter()) @@ -151,9 +155,7 @@ def test_unknown_provider_session_id_raises() -> None: def test_start_verification_is_blocked_once_locked_rejected() -> None: - """S2 §9/S8 §6 case 3: a customer whose `kyc_status` locked to `rejected` after exhausting - `KYC_MAX_ATTEMPTS` cannot start a fresh attempt -- only the admin override (S8 §4 row 5) may - reopen it.""" + """S2 §9/S8 §6 case 3: exhausted attempts lock `kyc_status`; only admin override reopens it.""" customer = _customer() uow = _FakeUow(customer) port = FakeKycAdapter() @@ -171,10 +173,80 @@ def test_start_verification_is_blocked_once_locked_rejected() -> None: service.start_verification(customer.id) +def test_sync_latest_verification_applies_a_live_verified_status_with_no_webhook() -> None: + """The safety net: a customer whose verdict webhook never arrives (e.g. localhost in local + dev) still gets approved once something asks the provider directly.""" + customer = _customer() + uow = _FakeUow(customer) + port = FakeKycAdapter() + service = _service(uow, port) + handle = service.start_verification(customer.id) + port.retrieved_statuses[handle.provider_session_id] = "verified" + + result = service.sync_latest_verification(customer.id) + + assert result == customer.id + assert customer.kyc_status is KycStatus.approved + session_row = uow.kyc_sessions.get_by_provider_session_id(handle.provider_session_id) + assert session_row is not None + assert session_row.status is KycSessionStatus.APPROVED + + +def test_sync_latest_verification_no_ops_when_still_pending_at_the_provider() -> None: + customer = _customer() + uow = _FakeUow(customer) + port = FakeKycAdapter() + service = _service(uow, port) + handle = service.start_verification(customer.id) + port.retrieved_statuses[handle.provider_session_id] = "processing" + + result = service.sync_latest_verification(customer.id) + + assert result is None + assert customer.kyc_status is KycStatus.pending + + +def test_sync_latest_verification_no_ops_when_already_terminal_and_never_calls_the_port() -> None: + """Once resolved, syncing again must not re-poll the provider at all.""" + customer = _customer() + uow = _FakeUow(customer) + port = FakeKycAdapter() + service = _service(uow, port) + handle = service.start_verification(customer.id) + service.apply_verification_verdict( + provider_session_id=handle.provider_session_id, stripe_status="verified" + ) + # Would flip the customer to rejected if (wrongly) called again. + port.retrieved_statuses[handle.provider_session_id] = "canceled" + + result = service.sync_latest_verification(customer.id) + + assert result is None + assert customer.kyc_status is KycStatus.approved + + +def test_sync_latest_verification_no_ops_when_no_session_exists_yet() -> None: + customer = _customer() + uow = _FakeUow(customer) + service = _service(uow, FakeKycAdapter()) + + assert service.sync_latest_verification(customer.id) is None + + +def test_sync_latest_verification_requires_a_configured_port() -> None: + customer = _customer() + uow = _FakeUow(customer) + service = _service(uow, FakeKycAdapter()) + handle = service.start_verification(customer.id) + assert handle is not None + unconfigured = KycService(uow, kyc_port=None, max_attempts=MAX_ATTEMPTS) # type: ignore[arg-type] + + with pytest.raises(KycPortNotConfiguredError): + unconfigured.sync_latest_verification(customer.id) + + def test_start_verification_allows_a_retry_below_the_attempt_cap() -> None: - """A single canceled attempt also sets `kyc_status = rejected` (ADR 9), but well below the - attempt cap this must not lock out a normal resubmission -- only "exhausted attempts" does - (S8 §6 case 3's own distinction).""" + """A canceled attempt sets `kyc_status = rejected` (ADR 9) but must not lock out a retry.""" customer = _customer() uow = _FakeUow(customer) service = _service(uow, FakeKycAdapter()) diff --git a/backend/tests/unit/test_kyc_session.py b/backend/tests/unit/test_kyc_session.py index b7cdb95..87de3bd 100644 --- a/backend/tests/unit/test_kyc_session.py +++ b/backend/tests/unit/test_kyc_session.py @@ -1,9 +1,4 @@ -"""Pure logic: `KycSession`'s single-transition guard (S2 §3.2) -- no database. - -The trigger-backed guarantee (a second transition rejected at the database too) is covered in -`tests/integration/test_kyc_session.py`, matching `settlement_obligation`'s split between an -application-level check (here) and its database backstop (there). -""" +"""Pure logic: `KycSession`'s single-transition guard, no database (S2 §3.2).""" from __future__ import annotations diff --git a/backend/tests/unit/test_logging.py b/backend/tests/unit/test_logging.py index 85081ef..b6810e8 100644 --- a/backend/tests/unit/test_logging.py +++ b/backend/tests/unit/test_logging.py @@ -1,11 +1,5 @@ -"""Structured logging and correlation-ID plumbing (S0 §7.4, OWASP A09). - -The correlation ID is the join key between a customer's bug report and the server-side trace. -These tests verify the plumbing: generation, context-variable storage, processor injection, -renderer selection, and logger usability. - -No ``unittest.mock.Mock`` — all assertions are against real structlog / contextvars behaviour. -""" +"""Structured logging and correlation-ID plumbing, against real structlog/contextvars behavior +(S0 §7.4, OWASP A09).""" from __future__ import annotations @@ -31,8 +25,7 @@ def test_new_correlation_id_returns_valid_uuid_string() -> None: cid = new_correlation_id() assert isinstance(cid, str) - # Must parse without raising — validates format and version. - parsed = uuid.UUID(cid) + parsed = uuid.UUID(cid) # must parse without raising assert str(parsed) == cid @@ -52,10 +45,8 @@ def test_set_and_get_round_trip() -> None: def test_fresh_context_returns_none() -> None: - """A context that has never called ``set_correlation_id`` must read ``None``, not crash.""" - # contextvars.Context() creates a truly empty context (no inherited values), unlike - # copy_context() which copies the current context's ContextVar values. - ctx = contextvars.Context() + """A context that never called `set_correlation_id` must read `None`, not crash.""" + ctx = contextvars.Context() # truly empty, unlike copy_context() result = ctx.run(get_correlation_id) assert result is None @@ -74,9 +65,7 @@ def test_add_correlation_id_injects_key_when_set() -> None: def test_add_correlation_id_omits_key_when_none() -> None: - """When no correlation ID is set, the key must be *absent* — not present with a ``None`` - value — so downstream consumers (JSON serializer, Application Insights) never see a null - ``correlation_id`` field.""" + """No correlation ID set: the key must be absent, not present with a `None` value.""" ctx = contextvars.Context() def _run() -> structlog.types.EventDict: @@ -114,10 +103,7 @@ def test_configure_logging_console_selects_console_renderer() -> None: def test_get_logger_returns_usable_bound_logger() -> None: configure_logging(json_output=False) logger = get_logger("test.logging") - # Emitting a line must not raise. We don't assert on output content — the processors may - # change — only that the returned object is usable and structlog-typed. - logger.info("smoke-test", key="value") - # structlog.get_logger returns a BoundLoggerLazyProxy; verify it quacks like a bound logger. + logger.info("smoke-test", key="value") # must not raise assert callable(getattr(logger, "info", None)) assert callable(getattr(logger, "warning", None)) assert callable(getattr(logger, "error", None)) diff --git a/backend/tests/unit/test_mcp_write_tools_validation.py b/backend/tests/unit/test_mcp_write_tools_validation.py new file mode 100644 index 0000000..b4014d6 --- /dev/null +++ b/backend/tests/unit/test_mcp_write_tools_validation.py @@ -0,0 +1,29 @@ +"""Argument validation for S13's write tools -- pure functions, no database or MCP transport.""" + +from __future__ import annotations + +import pytest + +from app.mcp.write_tools import _parse_uuid, _require_text + + +def test_parse_uuid_accepts_a_well_formed_uuid() -> None: + parsed = _parse_uuid("123e4567-e89b-12d3-a456-426614174000", field="customer_id") + + assert str(parsed) == "123e4567-e89b-12d3-a456-426614174000" + + +@pytest.mark.parametrize("malformed", ["not-a-uuid", "", "12345", " "]) +def test_parse_uuid_rejects_a_malformed_value(malformed: str) -> None: + with pytest.raises(ValueError, match="customer_id must be a valid UUID"): + _parse_uuid(malformed, field="customer_id") + + +def test_require_text_accepts_non_empty_text() -> None: + assert _require_text("a real reason", field="reason") == "a real reason" + + +@pytest.mark.parametrize("blank", ["", " ", "\t\n"]) +def test_require_text_rejects_blank_text(blank: str) -> None: + with pytest.raises(ValueError, match="reason is required"): + _require_text(blank, field="reason") diff --git a/backend/tests/unit/test_money.py b/backend/tests/unit/test_money.py index 42c311d..d6095cc 100644 --- a/backend/tests/unit/test_money.py +++ b/backend/tests/unit/test_money.py @@ -1,9 +1,4 @@ -"""Money/Units/Price value objects (ADR 16, S0 §4): dimension-mixing as a type error, not a habit. - -The four things a regulated ledger cannot tolerate, each pinned by a test group below: a float -reaching a money computation, two dimensions being added together, a JSON number silently losing -precision, and a pro-rata split whose parts do not sum back to the whole. -""" +"""Money/Units/Price value objects: dimension-mixing as a type error, not a habit (ADR 16).""" from __future__ import annotations @@ -248,14 +243,14 @@ def test_money_div_float_raises() -> None: def test_money_div_units_is_average_price() -> None: - """S3 §3.1's order.average_fill_price: total notional / total units filled.""" + """S3 §3.1's `order.average_fill_price`: total notional / total units filled.""" result = Money("1502.50") / Units("10") assert isinstance(result, Price) assert result == Price("150.25") def test_money_div_units_pins_the_exact_rounded_result() -> None: - """A division that does not come out even: the quantized result is pinned, not assumed.""" + """A division that does not come out even: the quantized result is pinned.""" assert Money("100.00") / Units("3") == Price("33.333333") @@ -265,20 +260,19 @@ def test_money_div_units_by_zero_raises() -> None: def test_units_div_money_raises() -> None: - """Units / Money is not a defined operation — it would be a fourth, meaningless dimension.""" + """Units / Money is not defined: it would be a fourth, meaningless dimension.""" with pytest.raises(TypeError): Units("2") / Money("10.00") # type: ignore[operator] def test_money_div_units_is_statically_typed_as_price() -> None: - """Fails `mypy --strict` if the `Money / Units` overload ever degrades to the base type.""" + """Fails `mypy --strict` if `Money / Units` degrades to the base type.""" result: Price = Money("1502.50") / Units("10") assert result == Price("150.25") def test_money_div_price_is_order_quantity() -> None: - """S9 §6's `RebalanceOrderService`: a dollar drift amount / the current price = the order - quantity to close it. The algebraic inverse of `Money / Units -> Price` above.""" + """S9 §6: drift amount / price = order quantity, the inverse of `Money / Units -> Price`.""" result = Money("1502.50") / Price("150.25") assert isinstance(result, Units) assert result == Units("10") @@ -294,13 +288,13 @@ def test_money_div_price_by_zero_raises() -> None: def test_price_div_money_raises() -> None: - """Price / Money is not a defined operation — it would be a fourth, meaningless dimension.""" + """Price / Money is not defined: it would be a fourth, meaningless dimension.""" with pytest.raises(TypeError): Price("2.00") / Money("10.00") # type: ignore[operator] def test_money_div_price_is_statically_typed_as_units() -> None: - """Fails `mypy --strict` if the `Money / Price` overload ever degrades to the base type.""" + """Fails `mypy --strict` if `Money / Price` degrades to the base type.""" result: Units = Money("1502.50") / Price("150.25") assert result == Units("10") diff --git a/backend/tests/unit/test_order_projection.py b/backend/tests/unit/test_order_projection.py index ce9c893..269d2da 100644 --- a/backend/tests/unit/test_order_projection.py +++ b/backend/tests/unit/test_order_projection.py @@ -1,6 +1,4 @@ -"""`OrderProjectionService.fold` (S3 §3.1/§8) — the standing `projection == fold(order_event)` -invariant, exercised as a pure function with no database involved. -""" +"""`OrderProjectionService.fold`: `projection == fold(order_event)`, pure, no database (S3 §3.1).""" from __future__ import annotations @@ -79,7 +77,7 @@ def test_fold_out_of_order_arrival_of_fill_before_accepted() -> None: accepted = _event(seq=2, event_type=OrderEventType.ACCEPTED) fill = _event(seq=3, event_type=OrderEventType.FILL, payload={"quantity": "10", "price": "20"}) - # Handed to fold() in arrival order (fill before accepted) -- seq still says accepted first. + # Handed to fold() in arrival order; seq still says accepted first. state = fold([submitted, fill, accepted], quantity_requested=Units("10")) assert state.status is OrderStatus.FILLED @@ -98,8 +96,7 @@ def test_fold_out_of_order_arrival_of_fill_before_accepted() -> None: def test_fold_is_independent_of_list_order_given_fixed_seq( fill_quantities: list[str], terminal: OrderEventType | None, seed: int ) -> None: - """The projection depends only on `seq`, never on the order events are handed to `fold()` in - (S3 §8's property-based requirement, foundation spec §10 case 4).""" + """The projection depends only on `seq`, never arrival order (S3 §8, foundation §10 case 4).""" quantity_requested = Units("100") canonical: list[OrderEvent] = [ _event(seq=0, event_type=OrderEventType.SUBMITTED), diff --git a/backend/tests/unit/test_outbox_task_router.py b/backend/tests/unit/test_outbox_task_router.py index acaef52..f118ae7 100644 --- a/backend/tests/unit/test_outbox_task_router.py +++ b/backend/tests/unit/test_outbox_task_router.py @@ -1,6 +1,4 @@ -"""`OutboxTaskRouter` (`app/services/ops/outbox_task_router.py`) -- pure routing logic, no -database or provider needed, unlike the CLI wiring (`outbox-worker` in `app/jobs/__init__.py`) -that constructs its real routes with live credentials.""" +"""`OutboxTaskRouter`: pure routing logic, no database or provider needed.""" from __future__ import annotations @@ -42,8 +40,7 @@ def test_an_unregistered_task_raises_rather_than_silently_dropping_the_row() -> def test_a_handler_raising_propagates_to_the_caller() -> None: - """`OutboxWorker.drain_once` is what actually catches this (retry-then-dead-letter) -- - `OutboxTaskRouter` itself must not swallow it first.""" + """`OutboxWorker.drain_once` catches this; `OutboxTaskRouter` must not swallow it first.""" def _boom(payload: dict[str, object]) -> None: raise RuntimeError("provider unavailable") diff --git a/backend/tests/unit/test_pagination.py b/backend/tests/unit/test_pagination.py index d99cce7..3e1040c 100644 --- a/backend/tests/unit/test_pagination.py +++ b/backend/tests/unit/test_pagination.py @@ -1,8 +1,4 @@ -"""Cursor pagination (S0 §8): opaque, tamper-evident cursors and the limit+1 `has_more` trick. - -Offset pagination is not exercised here at all — it is the thing this module replaces, on purpose, -so there is nothing to test. -""" +"""Cursor pagination: opaque, tamper-evident cursors and the limit+1 `has_more` trick (S0 §8).""" from __future__ import annotations @@ -31,7 +27,7 @@ def test_round_trips_a_single_value() -> None: def test_round_trips_a_compound_key() -> None: - """The whole point: a timestamp alone is not unique, so the id breaks the tie.""" + """A timestamp alone is not unique; the id breaks the tie.""" cursor = encode_cursor("2026-09-04T12:00:00+00:00", 42) assert decode_cursor(cursor) == ("2026-09-04T12:00:00+00:00", 42) @@ -72,8 +68,7 @@ def test_decode_rejects_truncated_cursor() -> None: def test_decode_rejects_tampered_payload() -> None: - """A single flipped character must fail the checksum, never silently decode to a different - (wrong-customer, wrong-row) sort key.""" + """A single flipped character must fail the checksum, never decode to a different sort key.""" cursor = encode_cursor("2026-09-04T12:00:00+00:00", 42) flipped_char = "A" if cursor[10] != "A" else "B" tampered = cursor[:10] + flipped_char + cursor[11:] @@ -88,8 +83,7 @@ def test_decode_rejects_oversized_cursor() -> None: def test_decode_rejects_non_list_payload() -> None: - """A hand-crafted cursor whose checksum is internally consistent but whose payload is not the - list shape `encode_cursor` always produces must still be rejected, not crash the decoder.""" + """A checksum-consistent cursor whose payload isn't the expected list shape must be rejected.""" payload = json.dumps({"not": "a list"}).encode("utf-8") checksum = hashlib.sha256(payload).digest()[:16] hostile = base64.urlsafe_b64encode(payload + checksum).decode("ascii").rstrip("=") @@ -173,8 +167,7 @@ def test_paginate_reports_no_more_rows_when_under_the_limit() -> None: def test_paginate_cursor_breaks_ties_on_the_compound_key() -> None: - """Two rows sharing a timestamp: the id in the compound key is what makes the boundary - unambiguous, so the next page starts strictly after (timestamp, id), not just timestamp.""" + """Two rows sharing a timestamp: the id makes the next-page boundary unambiguous.""" same_ts = "2026-09-04T12:00:00+00:00" rows = [ (same_ts, 1, "first"), diff --git a/backend/tests/unit/test_rebalance_order_service.py b/backend/tests/unit/test_rebalance_order_service.py index cf38c14..8d0bf89 100644 --- a/backend/tests/unit/test_rebalance_order_service.py +++ b/backend/tests/unit/test_rebalance_order_service.py @@ -1,8 +1,5 @@ -"""S9 §9's unit-level tests for `RebalanceOrderService` (S9 §6): sells-before-buys ordering, the -cash-buffer sizing arithmetic, and the buffer-drives-a-buy-to-zero edge case (S9 §8 item 5) -- all -runnable with no database, via the `OrderPlacer`/`InvestableCashProvider` `Protocol`s this module's -own docstring calls out. -""" +"""`RebalanceOrderService`: sells-before-buys ordering, cash-buffer sizing, and the +buffer-to-zero edge case, no database (S9 §6/§8 item 5/§9).""" from __future__ import annotations @@ -145,8 +142,7 @@ def test_the_cash_holding_never_itself_produces_an_order() -> None: def test_buy_notional_is_capped_by_investable_cash_minus_the_buffer() -> None: - """S9 §5/§6: `available_for_buys = investable(customer) - (portfolio_value * buffer_pct)`, - and a buy exceeding it is capped to exactly that headroom, not rejected outright.""" + """S9 §5/§6: a buy exceeding `investable - portfolio * buffer_pct` is capped, not rejected.""" security = uuid.uuid4() evaluation = _evaluation( [ @@ -176,8 +172,7 @@ def test_buy_notional_is_capped_by_investable_cash_minus_the_buffer() -> None: def test_the_cash_buffer_consuming_all_headroom_generates_no_buy_orders() -> None: - """S9 §8 item 5: a buffer constraint reducing a buy's sizing to zero is a valid outcome, not - an error -- a customer near-fully invested already, with little slack.""" + """S9 §8 item 5: a buffer reducing a buy's sizing to zero is valid, not an error.""" security = uuid.uuid4() evaluation = _evaluation( [ diff --git a/backend/tests/unit/test_repository.py b/backend/tests/unit/test_repository.py index ac526ba..92268a9 100644 --- a/backend/tests/unit/test_repository.py +++ b/backend/tests/unit/test_repository.py @@ -1,17 +1,5 @@ -"""`BaseRepository._tenant_scoped()` (S0 §5, ADR 14): pure, no-database behaviour. - -`_tenant_scoped()` only builds a `Select` statement — it never executes one — so the customer-id -guard it applies can be verified without a `UnitOfWork` ever entering its `with` block, i.e. -without touching PostgreSQL. That's what makes this a `tests/unit/` case rather than an -`tests/integration/` one; the query actually reaching the database (RLS, row visibility) is -covered by `tests/integration/test_repository.py`'s `WidgetRepository` suite. - -This module exists specifically to close the gap the Wave 2 ops repositories exposed: -`JobOutboxRepository`, `InboundEventRepository`, and `JobRunRepository` are for tables with no -customer identity (`job_outbox`, `inbound_event`, `job_run` — internal operational/audit tables), -so they configure no `customer_id_column`. `_tenant_scoped()` must fail loudly if ever called on -one of them, not silently build a nonsense `WHERE some_table.id = :customer_id` filter. -""" +"""`BaseRepository._tenant_scoped()`: pure statement-building, no database (S0 §5, ADR 14). +Must fail loudly when called on a repository with no `customer_id_column` configured.""" from __future__ import annotations @@ -28,7 +16,7 @@ class _Gizmo(Base): - """Throwaway entity for this module's `_tenant_scoped()` tests — never created in a database.""" + """Throwaway entity for this module's `_tenant_scoped()` tests, never created in a database.""" __tablename__ = "repo_unit_test_gizmo" @@ -38,23 +26,21 @@ class _Gizmo(Base): class _ScopedGizmoRepository(BaseRepository[_Gizmo]): - """A genuinely customer-scoped repository — the regression case: this must keep filtering.""" + """Genuinely customer-scoped repository; the regression case that must keep filtering.""" def __init__(self, uow: UnitOfWork) -> None: super().__init__(uow, entity=_Gizmo, customer_id_column=_Gizmo.customer_id) class _UnscopedGizmoRepository(BaseRepository[_Gizmo]): - """Stands in for `JobOutboxRepository` / `InboundEventRepository` / `JobRunRepository`: a - table with no customer identity, so no `customer_id_column` is configured.""" + """Stands in for a table with no customer identity, so no `customer_id_column` is configured.""" def __init__(self, uow: UnitOfWork) -> None: super().__init__(uow, entity=_Gizmo) def _customer_uow(customer_id: uuid.UUID) -> UnitOfWork: - """A `UnitOfWork` that is never entered — `_tenant_scoped()` only reads `.role`/`.customer_id`, - both plain properties, so no session/engine/database is needed for these tests.""" + """Never entered: `_tenant_scoped()` only reads `.role`/`.customer_id`, plain properties.""" return UnitOfWork(customer_id=customer_id, role=SessionRole.CUSTOMER) diff --git a/backend/tests/unit/test_security.py b/backend/tests/unit/test_security.py index 636ed24..696c2f1 100644 --- a/backend/tests/unit/test_security.py +++ b/backend/tests/unit/test_security.py @@ -1,12 +1,5 @@ -"""`@requires_role`, `@requires_ownership`, `@audited` (S0 §7.2). - -Pure unit tests — a bare `Flask()` app supplies request/app context (`requires_ownership`/ -`audited` read `flask.request`), and `@audited`'s "same transaction" guarantee is exercised -against the real `UnitOfWork` with a fake `Session` substituted via `session_factory` (S0 §5's own -documented extension point), never a real database. Faking the `Session` — rather than the whole -`UnitOfWork` — is what lets the rollback assertion below use `UnitOfWork`'s real `__exit__`, not a -hand-rolled stand-in for it. -""" +"""`@requires_role`, `@requires_ownership`, `@audited`: a bare `Flask()` app plus a real +`UnitOfWork` with a fake `Session`, never a real database (S0 §7.2/§5).""" from __future__ import annotations @@ -35,7 +28,7 @@ class _FakeUser: @pytest.fixture def flask_app() -> Flask: - """A bare app, not `create_app()` — this suite never touches a database or Redis.""" + """Bare app, not `create_app()`; this suite never touches a database or Redis.""" return Flask(__name__) @@ -90,8 +83,7 @@ def view() -> str: def test_requires_role_admits_a_staff_role_value_not_just_str_literals( monkeypatch: pytest.MonkeyPatch, flask_app: Flask ) -> None: - """Regression guard for the `StaffRole(enum.Enum)` bug (`tests/unit/test_staff.py`): a real - `Staff.role` value must satisfy `in ("adviser", "admin")` the same way a plain string does.""" + """Regression guard: a real `Staff.role` value must satisfy `in (...)` like a plain string.""" from app.models.identity.staff import StaffRole monkeypatch.setattr( @@ -210,8 +202,7 @@ def view(customer_id: uuid.UUID) -> str: class _FakeSession: - """Just enough of `sqlalchemy.orm.Session` for `UnitOfWork` to drive, with `rollback()` - discarding staged-but-uncommitted `add()`s the way a real ROLLBACK would.""" + """Just enough of `Session` for `UnitOfWork`, with `rollback()` discarding staged `add()`s.""" def __init__(self) -> None: self.added: list[Any] = [] @@ -340,10 +331,7 @@ def action(uow: UnitOfWork, customer_id: uuid.UUID) -> str: def test_audited_rolls_back_the_audit_row_when_the_action_raises( monkeypatch: pytest.MonkeyPatch, flask_app: Flask ) -> None: - """The required explicit case: an audited action can never succeed with no audit trail, and - symmetrically, an audit row can never survive an action that failed — the decorator writes to - `uow.session`, not to its own transaction, so `UnitOfWork.__exit__`'s rollback-on-exception - (S0 §5) discards both together.""" + """An audit row can never survive a failed action; rollback-on-exception discards both.""" monkeypatch.setattr(security, "current_user", _FakeUser(id=uuid.uuid4(), role="admin")) uow, fake_session = _uow() security.set_audit_sink(_FakeAuditSink(fake_session)) @@ -369,9 +357,7 @@ def action(uow: UnitOfWork, customer_id: uuid.UUID) -> str: def test_audited_allows_a_missing_target_customer_id( monkeypatch: pytest.MonkeyPatch, flask_app: Flask ) -> None: - """`admin_audit_log.target_customer_id` is nullable (S7 §5.2: resolving a - `reconciliation_break` with no single-customer attribution) -- an audited action with no - target customer still records, with `target_customer_id=None`, rather than raising.""" + """S7 §5.2: `target_customer_id` is nullable; a missing target still records, not raises.""" monkeypatch.setattr(security, "current_user", _FakeUser(id=uuid.uuid4(), role="admin")) uow, fake_session = _uow() security.set_audit_sink(_FakeAuditSink(fake_session)) diff --git a/backend/tests/unit/test_sql_tool_validator.py b/backend/tests/unit/test_sql_tool_validator.py index ae45bd6..b329f87 100644 --- a/backend/tests/unit/test_sql_tool_validator.py +++ b/backend/tests/unit/test_sql_tool_validator.py @@ -1,7 +1,5 @@ -"""`sql_tool_validator` (ADR 19 §4.3) against an adversarial table: multiple statements, a -trailing semicolon plus more SQL, write/DDL keywords, disallowed functions, off-allow-list -relations -- and a table of valid queries that must pass unchanged (S11 §7.1). -""" +"""`sql_tool_validator`: adversarial queries (multi-statement, DDL/DML, off-allow-list, disallowed +functions) rejected, valid queries pass unchanged (ADR 19 §4.3, S11 §7.1).""" from __future__ import annotations @@ -63,8 +61,7 @@ def test_accepts_valid_queries(sql: str) -> None: def test_normalized_sql_drops_comments() -> None: - """A second, incidental defense: the executed text is re-serialized, never the raw input, so - a comment-based obfuscation trick cannot survive into what actually runs (ADR 19 §4.3).""" + """The executed text is re-serialized, never the raw input, so comment-obfuscation fails.""" result = validate_query("SELECT * FROM v_holdings /* sneaky comment */") assert result.ok is True assert result.normalized_sql is not None diff --git a/backend/tests/unit/test_staff.py b/backend/tests/unit/test_staff.py index c609c61..f8de490 100644 --- a/backend/tests/unit/test_staff.py +++ b/backend/tests/unit/test_staff.py @@ -1,9 +1,4 @@ -"""`Staff` model invariants (S0 §7.2): the `AuthPrincipal` shape and the `role` enum. - -No database — the enum-domain assertion is against SQLAlchemy's column metadata, which is where -the ORM declares the value set the migration (`20260905_0948-..._add_identity_schemas_and_rls.py`) -already turns into a native Postgres enum. -""" +"""`Staff` model invariants: `AuthPrincipal` shape and `role` enum, no database (S0 §7.2).""" from __future__ import annotations @@ -35,13 +30,8 @@ def test_role_column_enforces_exactly_the_adviser_admin_value_set() -> None: def test_role_is_usable_as_a_plain_string_not_a_bare_enum_repr() -> None: - """The regression this guards: `StaffRole(enum.Enum)` (no `str` mixin) makes every - `principal.role in ("adviser", "admin")` comparison in `core/security.py` and the auth - controller silently False, which (a) skips mandatory adviser MFA at login and (b) makes - `@requires_role("adviser")` reject a real adviser. `StaffRole` must compare and format as a - bare string so every such call site (written against `Customer.role`'s plain-string contract) - works identically for a `Staff` principal. - """ + """Regression guard: `StaffRole` must compare/format as a plain string, or role checks + silently fail across `core/security.py` and the auth controller.""" staff = _staff(StaffRole.adviser) assert staff.role == "adviser" diff --git a/backend/tests/unit/test_trade_updates_consumer.py b/backend/tests/unit/test_trade_updates_consumer.py index 6e3a83c..0f27de1 100644 --- a/backend/tests/unit/test_trade_updates_consumer.py +++ b/backend/tests/unit/test_trade_updates_consumer.py @@ -1,6 +1,4 @@ -"""`TradeUpdatesConsumer.handle_message` (S3 §6, ADR 22) — pure, no websocket, matching ADR 22's -own stated consequence: "a test never opens a websocket." -""" +"""`TradeUpdatesConsumer.handle_message`: pure, no websocket opened (S3 §6, ADR 22).""" from __future__ import annotations @@ -84,8 +82,7 @@ def test_fill_event_is_intaken_keyed_on_execution_id() -> None: def test_source_event_id_for_non_fill_events_is_deterministic_with_no_execution_id() -> None: - """A redelivery of the byte-identical message must dedupe exactly like a redelivered fill — - verified directly on the pure helper (module docstring, ADR 7/22).""" + """A redelivered byte-identical message must dedupe like a redelivered fill (ADR 7/22).""" message = AlpacaTradeUpdateMessage.model_validate( _fill_message(event="canceled", execution_id=None) ) @@ -120,6 +117,6 @@ def test_untracked_alpaca_events_are_ignored_not_inserted(alpaca_event: str) -> def test_malformed_payload_fails_pydantic_validation_before_any_service_sees_it() -> None: uow = _Uow() with pytest.raises(ValidationError): - _consumer(uow).handle_message({"event": "fill"}) # missing required `order`/`timestamp` + _consumer(uow).handle_message({"event": "fill"}) # missing order/timestamp assert uow.inbound_events.created == [] diff --git a/backend/tests/unit/test_trading_calendar.py b/backend/tests/unit/test_trading_calendar.py index f3ef0be..6e00dbd 100644 --- a/backend/tests/unit/test_trading_calendar.py +++ b/backend/tests/unit/test_trading_calendar.py @@ -1,8 +1,4 @@ -"""`CachedTradingCalendar` (S4 §3.4): a cache miss must never be conflated with a holiday. - -Pure unit test against a duck-typed fake repository -- no database needed, matching -`backend/CLAUDE.md`'s `tests/unit/` layer. -""" +"""`CachedTradingCalendar`: a cache miss must never be conflated with a holiday (S4 §3.4).""" from __future__ import annotations @@ -61,8 +57,7 @@ def test_is_trading_day_reflects_a_fetched_holiday_row() -> None: def test_cache_miss_raises_rather_than_reading_as_a_holiday() -> None: - """S4 §3.4's core rule: an unfetched date is an operational condition, never a silent - `is_trading_day=False`.""" + """S4 §3.4: an unfetched date is an operational condition, never a silent `False`.""" repo = _FakeCalendarCacheRepo() calendar = CachedTradingCalendar(repo) # type: ignore[arg-type] diff --git a/backend/tests/unit/test_watermark.py b/backend/tests/unit/test_watermark.py index 120227a..165d3df 100644 --- a/backend/tests/unit/test_watermark.py +++ b/backend/tests/unit/test_watermark.py @@ -25,11 +25,7 @@ def test_as_published_is_flagged_as_published() -> None: def test_live_captures_the_instant_once() -> None: - """Two reads in one unit of work must see the same world. - - If the cutoff were re-evaluated per query, a correction landing mid-transaction could make a - balance disagree with the postings it was derived from. - """ + """Two reads in one unit of work must see the same world.""" watermark = Watermark.live() assert watermark.cutoff == watermark.cutoff @@ -40,7 +36,7 @@ def test_live_accepts_an_injected_clock() -> None: def test_naive_datetime_is_rejected_by_as_published() -> None: - """A naive datetime silently assumes the server's zone — the ADR 12 day-boundary bug.""" + """A naive datetime silently assumes the server's zone (ADR 12 day-boundary bug).""" with pytest.raises(ValueError, match="timezone-aware"): Watermark.as_published(datetime(2026, 8, 31, 21, 5, 0)) # noqa: DTZ001 diff --git a/backend/uv.lock b/backend/uv.lock index 7b36b7c..b136885 100644 --- a/backend/uv.lock +++ b/backend/uv.lock @@ -257,6 +257,7 @@ dependencies = [ { name = "flask-talisman" }, { name = "flask-wtf" }, { name = "gunicorn" }, + { name = "mcp" }, { name = "openai-agents" }, { name = "plaid-python" }, { name = "psycopg", extra = ["binary"] }, @@ -298,6 +299,7 @@ requires-dist = [ { name = "flask-talisman", specifier = ">=1.1" }, { name = "flask-wtf", specifier = ">=1.2" }, { name = "gunicorn", specifier = ">=26.2.0" }, + { name = "mcp", specifier = ">=2.1.1" }, { name = "openai-agents", specifier = ">=0.22.0" }, { name = "plaid-python", specifier = ">=27.0" }, { name = "psycopg", extras = ["binary"], specifier = ">=3.2" }, diff --git a/docker-compose.yml b/docker-compose.yml index 5648c86..985dc12 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -97,6 +97,31 @@ services: redis: condition: service_healthy + # S13/ADR 24's MCP agent surface -- a separate ASGI process, same image as `backend`, different + # entrypoint (same "different process, same database" shape `worker` already establishes). + mcp-server: + profiles: ["app"] + build: + context: ./backend + container_name: trueup-mcp-server + command: ["python", "-m", "app.mcp.entrypoint"] + env_file: .env + environment: + DATABASE_URL: postgresql+psycopg://trueup_app:trueup_app@db:5432/trueup + DATABASE_URL_WORKER: postgresql+psycopg://trueup_worker:trueup_worker@db:5432/trueup + DATABASE_URL_OWNER: postgresql+psycopg://trueup_owner:trueup_owner@db:5432/trueup + DATABASE_URL_CHAT: postgresql+psycopg://trueup_chat_readonly:trueup_chat_readonly@db:5432/trueup + REDIS_URL: redis://redis:6379/0 + MCP_SERVER_HOST: 0.0.0.0 + MCP_SERVER_PORT: "8001" + ports: + - "8001:8001" + depends_on: + db: + condition: service_healthy + redis: + condition: service_healthy + frontend: profiles: ["app"] build: diff --git a/docs/project-rubrics/scoring.md b/docs/project-rubrics/scoring.md new file mode 100644 index 0000000..8598213 --- /dev/null +++ b/docs/project-rubrics/scoring.md @@ -0,0 +1,19 @@ +# Scoring + +Out of 100. We share this deliberately: knowing exactly how you are graded and still choosing what to sacrifice is the skill being tested. + +| Area | Points | What earns them | +| :--- | :--- | :--- | +| Domain command | 30 | The vertical's mechanics live in your schema and your state machines, not your README. The track's domain gauntlet handled correctly. Vocabulary used precisely under questioning. | +| A system that runs | 25 | Deployed, stable through the demo, core loop working end to end. The three screens that matter show default, loading, empty, error and one edge state. | +| Integration reality | 20 | Two or more genuinely live sandbox integrations. Verified signatures, idempotent consumers, graceful degradation when a provider is down. Honest real-versus-simulated labelling. | +| Live fire | 15 | The system survives our scripted attacks. When something breaks, you diagnose it in front of us instead of defending it. | +| Judgment and communication | 10 | Questions asked early and well. Assumptions written down. A credible cut list. A decision log a stranger can follow. | + +Automatic fails, regardless of everything else: + +- Localhost only, or a video in place of a URL. +- A simulated integration presented as live. +- UPDATE or DELETE on money rows. Anywhere. Ever. +- Live-mode API keys, real money, or real personal data. +- Secrets committed to the repo. \ No newline at end of file diff --git a/docs/specs/frontend/2026-09-05-frontend-completion-design.md b/docs/specs/frontend/2026-09-05-frontend-completion-design.md new file mode 100644 index 0000000..c02e978 --- /dev/null +++ b/docs/specs/frontend/2026-09-05-frontend-completion-design.md @@ -0,0 +1,225 @@ +# Frontend completion — design + +## Context + +The frontend (`frontend/src`) is not a greenfield build: five prior phases produced ~204 files +across 12 customer routes and 4 admin routes, a 93-token design system with zero hardcoded-color +violations, a clean `apiClient.js` (CSRF, idempotency keys, RFC 9457 error normalization), and a +passing `npm run lint` / `npm run build`. What's missing is real: **zero test files** despite +`frontend/CLAUDE.md`'s "no component is done without a test," and **six domains built against +`mockClient.js` instead of the API** — committed under a commit literally titled "Phase 4 - mocked +domains." `App.jsx`'s own comment names them: portfolio, lots, fees, chat, admin customers, +statement export. + +A three-way audit (mock inventory, backend API surface, spec conformance) found the six mocks split +two ways: + +- **Backend already has the route** (portfolio, fees, chat, admin customer fees) — pure frontend + wiring gaps. +- **No backend route exists at all** (lots, admin customers directory/detail/KYC-override, + statement export) — these are exactly S8's F10 finding from the earlier backend audit: six + documented-but-unbuilt routes. + +Two more gaps surfaced beyond the six named mocks: `structure.md §7` mandates a `hooks/useSSE` for +real-time push (order fill, KYC verdict, new break) built on `S12 §6`/`ADR 20`'s Redis Pub/Sub +fan-out — neither the backend endpoint nor the frontend hook exists, only chat has SSE. And the fee +payment-method form collects a card brand/last-4 as plain strings instead of tokenizing through +Stripe Elements, despite `@stripe/stripe-js` already being a dependency and `GET /identity/config` +already serving the publishable key needed to mount it. + +The user's directive — "nothing should be mocked, ensure everything is finished" — was tested +against three scope questions, each decided in favor of the larger, more complete option: + +1. **Missing backend routes**: build them (not leave three domains mocked, not remove them). +2. **Order-form pricing**: reuse `GET /portfolios/models` for the security picker; the customer + enters `reference_price` (already a required API field) rather than inventing a quote source. +3. **Test depth**: exhaustive — one colocated test file per component, matching the literal text of + `frontend/CLAUDE.md` and `structure.md §8`, not a risk-prioritized subset. +4. **Real-time push**: build the full fan-out (backend SSE endpoints + Redis Pub/Sub publish sites + + frontend `useSSE` + its three consumers), not defer it. +5. **Stripe Billing**: wire real Stripe Elements, tokenizing in the browser so card data never + touches Trueup's servers. + +This spec is the design for closing all of it. It does not re-litigate those five decisions or the +backend remediation plan already executed and merged (`carefully-and-thoroughly-read-joyful-riddle` +plan, PRs #5–#6) — it starts from `main` at that point. + +## Scope + +**In scope:** +- Six new/extended backend routes (S8 F10): `/lots`, `/statements//export`, + `/admin/customers`, `/admin/customers/`, `/admin/kyc-overrides/`, + `/admin/customers//fees` (the last already partially served by `GET /fees?customer_id=`). +- Real-time push backend: `GET /api/v1/events/stream`, `GET /api/v1/admin/events/stream`, and the + three publish sites (`OrderService`, `KycService`/`AccountApprovalService`, + `ReconciliationService`), per `S12 §6`'s already-complete wire design. +- Frontend: replace all six `mockClient`-backed `api/*.js` modules with real `apiClient` calls; + build `hooks/useSSE` and its three feature consumers; replace `useChatStream`'s fake token-split + with a real `fetch` + `ReadableStream` consumer of the existing chat SSE endpoint; replace + `PaymentMethodForm`'s plain-string capture with Stripe Elements. +- Vitest + React Testing Library installed and wired into `npm test` and `Makefile`; one colocated + test file per component/hook/api module/route-guard, per `structure.md §8`. + +**Out of scope (explicitly deferred, not silently dropped):** +- CI/CD wiring for the frontend (Phase 3 of the backend plan already covers this ground generally; + extending it to frontend jobs is a follow-up once tests exist to run). +- Azure deployment of the frontend container (Dockerfile already exists from Phase 0; deploying it + is Phase 5 of the backend plan, unchanged). +- Anything in `docs/specs/frontend/structure.md §9`'s still-open question 2 (`/admin/breaks/:id` + hydrating from the list vs. a dedicated fetch) — no new information changes that answer; current + hydrate-from-list behavior stands. + +## Architecture + +### A. Backend: the six S8 routes + +All five new endpoints follow the existing controller pattern exactly (Pydantic request/response +views in `app/views/`, a thin controller in `app/controllers/api/` or `app/controllers/admin/`, a +service method, `@requires_role`/inline ownership matching neighboring routes, `@audited` on every +privileged write per `ADR 15`). + +- **`GET /api/v1/lots`** (customer route, `S8 §3`) — new `LotsService` read method returning open + and (optionally, `?include_closed=`) closed lots for the caller's `customer_id`, with + `is_provisional` computed from `designation_window_closes_at` vs. now, and wash-sale adjustment + fields surfaced per `TaxLot.adjusted_basis`. Reuses `TaxLotRepository` (`app/models/ledger/tax_lot.py`) + already built for S5 — no new repository method beyond a customer-scoped list query. + +- **`GET /api/v1/statements//export`** (`S8 §5`, FR-36) — a new controller action beside the + existing `statements.py` routes. Reads the published snapshot exactly as `get_statement` does + (never a live recompute — same "not yet published" 404 if absent, per spec edge case 1), plus the + period's realized lot consumptions (S5) including `is_provisional` and any + `wash_sale_adjustment` rows, and renders CSV (`text/csv`, `Content-Disposition: attachment`). No + PDF (spec names it out of scope for v1). + +- **`GET /api/v1/admin/customers`** (`S8 §4`) — paginated directory using the existing + `app/core/pagination.py` helper; `?query=` matches email case-insensitively (name matching is + deferred per the spec's own note — S2 carries no name field yet). `@requires_role("adviser", + "admin")`. + +- **`GET /api/v1/admin/customers/`** — aggregates existing read paths under the adviser RLS + branch: `ValuationService.value_book` (the *same* call `/valuation/balance` makes — spec edge case + 4's "must agree exactly" requirement, satisfied by literally not duplicating the aggregation), KYC + and account-approval status, and **any open reconciliation break for this customer**, surfaced as + a prominent field per spec edge case 2 — not a separate fetch the frontend has to remember to make. + +- **`POST /api/v1/admin/kyc-overrides/`** — the concrete route for S2 §9's open + parameter. Only valid when `customer.kyc_status == REJECTED` and the latest `KycSession.attempt_number + >= KYC_MAX_ATTEMPTS` (the existing locked-rejected condition already computed in + `kyc_service.py:47`, not a new column) — resets `kyc_status` to `pending` and allows a fresh + `KycSession`. `@audited("identity.kyc.override")`. + +- **`GET /api/v1/admin/customers//fees`** — thin adviser-scoped wrapper over the same + `FeeChargeService` read path `GET /fees?customer_id=` already uses; kept as its own route per the + spec's route table (adviser fee view vs. customer fee view are named separately in `S8 §4`), but + implemented as a one-line delegation, not a second aggregation. + +`/identity/status/` also gets a small extension here: distinguish "rejected, locked" +from "rejected, resubmittable" in its response (spec edge case 3), using the same +`attempt_number >= max_attempts` check the override route reads, rather than inventing a new status +value the customer-facing copy has to interpret. + +### B. Backend: real-time push (S12 §6 / ADR 20) + +The wire design is already fully specified — this implements it, not designs it: + +- Two SSE routes: `GET /api/v1/events/stream` (customer, ownership-scoped) and + `GET /api/v1/admin/events/stream` (adviser, role-scoped) — long-lived generators identical in + shape to `chat.py`'s existing `send_message` SSE handler, subscribing to + `customer::events` or `adviser:events` via the existing `redis.Redis` client + (`app/extensions.py:make_redis`) on connection open, unsubscribing on disconnect. +- Message shape fixed by spec: `{event_type, entity_id, summary}` — a pointer, never the entity + itself; the frontend's reaction is always a re-fetch of the relevant `GET` endpoint. +- Three publish sites, each firing **after** its own commit (never inside the transaction, per + S0 §5's no-I/O-in-a-transaction rule, restated explicitly by S12 §6): `OrderService` on a fill or + terminal `order_event`; `KycService`/`AccountApprovalService` on a status change; `ReconciliationService` + on opening a `reconciliation_break`. Adding a fourth is not in scope — three matches the spec's + named list exactly. +- No new infra: same Redis instance already used for sessions/rate limits (ADR 13/15's "never holds + financial state" is preserved — a Pub/Sub message is an ephemeral pointer, not a fact of record). + +### C. Frontend: mock removal + +Each of the six `api/*.js` modules is rewritten to call `apiClient` instead of `mockClient`, matching +the request/response shapes the backend audit already pinned down exactly (money/units/price as +fixed-point strings, `code`-only error bodies). Two need a field-mapping layer because names differ +from what the mock invented: + +- `feesApi.js` — backend's `accrual_to_date` / `high_water_mark.peak_value` map onto the same UI + concepts the mock called `accrual.month_to_date_gain` etc.; the mapping lives in the api module, + not spread across components. +- `chatApi.js` / `useChatStream.js` — replaced with a real `fetch(..., {method: 'POST'})` + + `response.body.getReader()` loop parsing `data: {...}\n\n` frames per the three documented shapes + (`token`, `completed`, `error`); `EventSource` cannot be used since the endpoint is a CSRF-bearing + POST. +- `portfoliosApi.js` — drops the fabricated `getSecurities()` price table entirely; + `OrderForm` now sources its security picker from `GET /portfolios/models`'s + `target_weights[].{security_id, symbol}` and asks the customer for `reference_price` directly + (decision 2 above) — the field the API already requires, so no contract change. +- `lotsApi.js`, `adminCustomersApi.js`, `statements/export` — become thin real clients once §A's + routes exist; no mapping needed, response shapes are authored to match the frontend's existing + expectations since both are built in this change. + +`mockClient.js` is deleted once its last consumer is migrated — not left as unreferenced dead code. + +### D. Frontend: `useSSE` and its consumers + +One hook (`src/hooks/useSSE.js`), one connection per authenticated session, opened once by +`SessionContext` (mirroring how `useChatStream` already manages its own connection) and exposing a +subscribe-by-`event_type` API so a feature registers a callback rather than the hook knowing about +every feature. Three consumers, exactly as `structure.md §7` specifies: + +- `orders` feature: a `fill` push re-fetches and patches the matching row in place — no full list + refetch. +- `SessionContext`: a KYC/approval push re-fetches `GET /auth/session` so onboarding gating updates + without a manual reload. +- `admin-breaks` feature: a new-break push re-fetches the list's first page and prepends any row not + already present. + +No connection (tab backgrounded, disconnected) degrades to nothing — every screen's own `GET` on +mount stays the source of truth, exactly as ADR 20 requires. + +### E. Frontend: real Stripe Elements for billing + +`PaymentMethodForm` mounts Stripe Elements (`@stripe/stripe-js`, already a dependency) using the +publishable key from the existing `GET /identity/config`, collects the card via Stripe's own +`CardElement` (never touching Trueup's servers with raw card data), and submits the resulting +`payment_method_id` to the existing `POST /payment-methods`. This is the same integration pattern +`OnboardingPage`'s Stripe Identity step already uses for the KYC provider key, applied to Billing. + +### F. Testing + +Vitest + `@testing-library/react` + `@testing-library/jest-dom` + `jsdom`, wired as `npm test` in +`package.json` and a `frontend-test` target in the root `Makefile` (mirroring the backend's +`test-unit`/`test-integration` pattern). Per `structure.md §8`, colocated one-file-per-unit: + +- **Generic `components/`** (13 dirs): render + interaction + keyboard/focus-visible tests — the + shared accessibility contract, tested once. +- **Feature components** (~60 files across 12 features): render tests per data shape, including the + provisional/adjusted/dunning variant named per-domain in `design-system.md §8`. +- **Feature hooks** (~20 files): success/error/idempotent-retry against a mocked `api/*.js`. +- **api modules** (13 files): request-shape and error-mapping tests against a mocked `fetch`. +- **Forms**: validation, submit-disabled-while-submitting, submit-failure-keeps-input-filled. +- **`ChatWindow`/`useChatStream`**: mocked SSE stream, incremental token rendering, + `tool_calls` disclosure. +- **Route guards** (`SessionContext`, `guards.jsx`): tested once at the router/context level. +- **Loading/empty/error states**: the `structure.md §6` table is the checklist — each named cell + becomes an explicit test case, not an implicit "renders" assertion. + +## Data flow / error handling + +No change to the established contracts: `apiClient.js`'s CSRF/idempotency/error-normalization stays +the single point of contact; every error still surfaces as `ApiError{status, code, ...}` and every +new form follows the existing inline-error, keep-input-filled pattern already used by +`DepositForm`/`WithdrawForm`. The two new backend surfaces (admin aggregation, SSE) both read +already-existing services rather than introducing a second source of truth, satisfying spec edge +case 4 (`/valuation/balance` and `/admin/customers/` must agree exactly). + +## Testing (verification for this change itself) + +- Backend: new routes get the same four-layer coverage (`tests/unit`, `tests/integration`, + `tests/api`, `tests/contract` where applicable) as every existing S8 route; `make check` green; + Alembic round-trip if any schema changes (none anticipated — all new routes read existing tables). +- Frontend: `npm test` green, `npm run lint`, `npm run build` green; manual smoke of the full loop + (register → KYC → bank link → deposit → assign portfolio → order → SSE fill push → statement → + export) against a running `make up && make dev` backend. +- `mockClient.js` has zero remaining importers before deletion — verified by grep, not assumption. diff --git a/docs/specs/frontend/design-system.md b/docs/specs/frontend/design-system.md index aad85cc..8d84ffd 100644 --- a/docs/specs/frontend/design-system.md +++ b/docs/specs/frontend/design-system.md @@ -21,14 +21,17 @@ energy), and a generic enterprise-SaaS look (rounded cards, soft drop shadows, a blue). Neither says "we handle this correctly," which is the one thing this product actually needs to say. -The concrete reference point is a **ledger, not a dashboard** — the object this whole system is -built around (`ADR 1`: an append-only, bitemporal posting ledger; `docs/specs/6-restatement-engine.md`; -`docs/specs/5-tax-lots-and-corporate-actions.md`). A well-kept ledger is quiet, exact, and legible at -a glance: flat pages, ruled lines, ink on paper, figures that line up in columns. That vocabulary — -hairline rules instead of drop shadows, restrained near-black "ink" instead of a bright brand color, -tabular figures that align — is what this system is built from. It is a deliberate departure from -both the warm-cream/serif-display and the near-black/neon-accent looks that AI-generated design -defaults to; neither reads as "audited," which is the actual job here. +The concrete reference point is a **vault, not a dashboard** — safekeeping, not a growth-app +feed. A private bank's safety-deposit room is quiet, exact, and legible at a glance: flat surfaces, +ruled lines, deep navy steel and warm ivory paper, brass fixtures that show age without ever +looking worn. That vocabulary — hairline rules instead of drop shadows, a near-black navy "ink" +instead of a bright brand blue, a restrained brass accent standing in for the vault door's own +hardware — is what this system is built from. It is a deliberate departure from both the +warm-cream/serif-display and the near-black/neon-accent looks that AI-generated design defaults to; +neither reads as "your money is safe here," which is the actual job. The append-only, bitemporal +posting ledger underneath (`ADR 1`; `docs/specs/6-restatement-engine.md`; +`docs/specs/5-tax-lots-and-corporate-actions.md`) is still what the numbers on screen are honest +about — the vault is what holds them, not a rebranding of what they are. What this system optimizes for, in order: 1. **Unambiguous state.** A reconciliation break, a failed deposit, a restated figure, a pending @@ -46,12 +49,12 @@ What this system optimizes for, in order: | Token | Hex | Role | | --- | --- | --- | -| `ink` | `#12202E` | Primary text, headings, primary button fill — the "ledger ink" | -| `accent` (verdigris) | `#1F6E68` | Interactive elements: links, focus, selected state, the as-corrected/restated indicator, primary chart line | -| `success` | `#1E6B3C` | Settled, reconciled, approved, gains | -| `warning` | `#9C5B12` | Pending, aging, needs-attention-soon | -| `error` | `#A32E27` | Reconciliation break, failed/bounced, rejected, losses | -| `paper` | `#F5F6F7` | App background — cool, near-neutral, not warm cream | +| `ink` | `#101B2D` | Primary text, headings, primary button fill — deep navy steel | +| `accent` (brass) | `#896724` | Interactive elements: links, focus, selected state, the as-corrected/restated indicator, primary chart line | +| `success` | `#1F6B47` | Settled, reconciled, approved, gains | +| `warning` | `#8A520A` | Pending, aging, needs-attention-soon | +| `error` | `#8C2F27` | Reconciliation break, failed/bounced, rejected, losses | +| `paper` | `#F6F3EA` | App background — warm ivory, not cool office-gray | Five chromatic tokens plus the paper base — deliberately short. No tints-of-blue ramp, no brand-gradient. `ink` doing double duty as both primary text color and primary action color (rather @@ -59,13 +62,15 @@ than adding a sixth "primary button blue") is itself a restraint decision: this authoritative voice, not a marketing color separate from its content color. **Rationale for the specific hues:** `ink` is a near-black navy rather than true black or a bright -brand blue — it reads as "fountain-pen ink on a ledger page," not "corporate blue." `accent` is a -deep verdigris (aged-copper patina, the color bank fixtures and old ledger bindings actually oxidize -to) rather than the generic SaaS blue (`#4F7CFF`-family) or the AI-cliché terracotta — it is used -narrowly enough (§2.4) that its scarcity is part of the signal. `success`/`error` are deep forest -green and brick red rather than saturated traffic-light green/red — a callback to the literal -double-entry convention of red ink for a negative figure, deep enough to read as considered rather -than a dashboard warning light. +brand blue — it reads as "bank-vault steel," not "corporate blue." `accent` is a restrained brass +(the color of well-kept safety-deposit-box hardware and vault-door fixtures) rather than the +generic SaaS blue (`#4F7CFF`-family) or the AI-cliché terracotta — it is used narrowly enough (§2.4) +that its scarcity is part of the signal, and it is deliberately darker than a decorative "gold" — +this is hardware, not jewelry. `success`/`error` are deep forest green and brick red rather than +saturated traffic-light green/red — a callback to the literal double-entry convention of red ink +for a negative figure, deep enough to read as considered rather than a dashboard warning light. +`paper` is warm ivory rather than the previous cool office-gray — closer to archival document stock +than a screen background, which is what a safety-deposit room's own paperwork actually looks like. ### 2.2 Full token table (light + dark) @@ -76,23 +81,23 @@ surface.** The metaphor holds in both directions rather than being patched. | Token | Light | Dark | Usage | | --- | --- | --- | --- | -| `--color-paper` | `#F5F6F7` | `#0F151B` | App canvas background | -| `--color-surface` | `#FFFFFF` | `#1A222B` | Card/panel background | -| `--color-surface-sunken` | `#ECEEF0` | `#141B22` | Table row stripe, inset wells | -| `--color-hairline` | `#DBDFE3` | `#2B343E` | Default border/divider | -| `--color-border-strong` | `#B9C0C7` | `#3E4954` | Input borders, emphasized dividers | -| `--color-text` | `#12202E` | `#E9EDF0` | Primary text | -| `--color-text-secondary` | `#3A4149` | `#B7C0C9` | Secondary text, labels | -| `--color-text-muted` | `#5B6570` | `#7C8792` | Captions, timestamps, disabled — never for primary data | -| `--color-accent` | `#1F6E68` | `#4FBFB0` | Links, focus ring, selected state, restated indicator | -| `--color-accent-strong` | `#175450` | `#3AA394` | Hover/pressed accent | -| `--color-accent-subtle` | `#E3EFEC` | `#12332E` | Selected-row tint, accent-tinted chip background | -| `--color-success` | `#1E6B3C` | `#4CAF6E` | Text/icon on success state | -| `--color-success-subtle` | `#E5F2E9` | `#14301F` | Success badge/banner background | -| `--color-warning` | `#9C5B12` | `#D9A441` | Text/icon on warning state | -| `--color-warning-subtle` | `#FBF0DF` | `#3A2C10` | Warning badge/banner background | -| `--color-error` | `#A32E27` | `#E2635A` | Text/icon on error state | -| `--color-error-subtle` | `#FBEAE8` | `#3A1613` | Error badge/banner background | +| `--color-paper` | `#F6F3EA` | `#0F141C` | App canvas background | +| `--color-surface` | `#FFFFFF` | `#1A212B` | Card/panel background | +| `--color-surface-sunken` | `#EEE7D3` | `#141922` | Table row stripe, inset wells | +| `--color-hairline` | `#DED3B7` | `#2C343F` | Default border/divider | +| `--color-border-strong` | `#988752` | `#3F4855` | Input borders, emphasized dividers | +| `--color-text` | `#101B2D` | `#EDEAE3` | Primary text | +| `--color-text-secondary` | `#3D4A5E` | `#C9C2B6` | Secondary text, labels | +| `--color-text-muted` | `#555D6D` | `#948D7F` | Captions, timestamps, disabled — never for primary data | +| `--color-accent` | `#896724` | `#CFA959` | Links, focus ring, selected state, restated indicator | +| `--color-accent-strong` | `#694F1C` | `#B08B40` | Hover/pressed accent | +| `--color-accent-subtle` | `#F0E4C6` | `#342A14` | Selected-row tint, accent-tinted chip background | +| `--color-success` | `#1F6B47` | `#4DB283` | Text/icon on success state | +| `--color-success-subtle` | `#E1F0E7` | `#153023` | Success badge/banner background | +| `--color-warning` | `#8A520A` | `#D8A041` | Text/icon on warning state | +| `--color-warning-subtle` | `#FAEBD2` | `#392A11` | Warning badge/banner background | +| `--color-error` | `#8C2F27` | `#E0675C` | Text/icon on error state | +| `--color-error-subtle` | `#F6E1DD` | `#391613` | Error badge/banner background | Theme selection follows OS/user preference (`prefers-color-scheme`) with an explicit in-app toggle persisted per user — standard behavior, not specified further here. @@ -104,18 +109,26 @@ eyeballed: | Pairing | Ratio | Floor | | --- | --- | --- | -| `text` on `paper` (light) | 15.3:1 | AAA (7:1) | -| `text-secondary` on `paper` | 9.6:1 | AAA | -| `text-muted` on `paper` | 5.5:1 | AA (4.5:1) — captions/timestamps only, see below | -| `accent` on `paper`/`surface` | 5.6–6.0:1 | AA | -| `success` on `paper` | 6.0:1 | AA | -| `error` on `paper` | 6.5:1 | AA | -| `warning` on `paper` | 5.0:1 | AA | -| white text on `ink` (primary button) | 15.3:1 | AAA | -| white text on `accent` (accent button) | 6.0:1 | AA | -| `text` on `paper` (dark) | 15.6:1 | AAA | -| `accent`/`success`/`warning` on `paper` (dark) | 6.7–8.2:1 | AA/AAA | -| `error` on `paper` (dark) | 5.4:1 | AA | +| `text` on `paper` (light) | 15.6:1 | AAA (7:1) | +| `text-secondary` on `paper` | 8.1:1 | AAA | +| `text-muted` on `paper` | 6.0:1 | AA (4.5:1) — captions/timestamps only, see below | +| `accent` on `paper`/`surface` | 4.7–5.2:1 | AA | +| `success` on `paper` | 5.8:1 | AA | +| `error` on `paper` | 7.4:1 | AA | +| `warning` on `paper` | 5.8:1 | AA | +| `border-strong` on `paper` (non-text UI, WCAG 1.4.11) | 3.2:1 | AA (3:1) | +| white text on `ink` (primary button) | 17.3:1 | AAA | +| `accent` on `accent-subtle` (restated badge, §8.1) | 4.1:1 | AA | +| `text` on `paper` (dark) | 15.4:1 | AAA | +| `accent`/`success`/`warning` on `paper` (dark) | 7.1–8.3:1 | AAA | +| `error` on `paper` (dark) | 5.5:1 | AA | +| `accent` on `accent-subtle` (dark) | 6.4:1 | AAA | + +The previous version of this table checked "white text on `accent` (accent button)" — but §7.1's +Button spec has only three variants (Primary = `ink` fill, Secondary = outline, Destructive = +`error` fill), and no button is ever accent-filled. That pairing checked a combination the +component spec doesn't use, so it's replaced above with the pairing `accent` is actually used in: +text on `accent-subtle`, the restated-figure badge from §8.1. Rule: `text-muted` clears AA for large text and non-critical labels only. **Any figure that is a balance, return, price, or tax value uses `text` or `text-secondary` (or the relevant semantic @@ -128,7 +141,7 @@ legibility for decorative restraint. with an icon or a text label (a break row says "Open · 4d" in error color *and* the word "Open"; a settled deposit gets a checkmark, not just green text). This is a colorblind-safety requirement, not a nicety, for a platform where a missed "needs attention" state is a real financial risk. -- **`accent` (verdigris) is reserved** for: interactive elements (links, focus rings), the current +- **`accent` (brass) is reserved** for: interactive elements (links, focus rings), the current selection, and — deliberately — the visual marker for a **restated/as-corrected figure** (§8.1). It does not appear as generic decoration. Its scarcity is what makes "this number was corrected" register at a glance. diff --git a/docs/superpowers/specs/2026-09-06-nn3-correction-and-money-row-immutability-design.md b/docs/superpowers/specs/2026-09-06-nn3-correction-and-money-row-immutability-design.md new file mode 100644 index 0000000..7a770cd --- /dev/null +++ b/docs/superpowers/specs/2026-09-06-nn3-correction-and-money-row-immutability-design.md @@ -0,0 +1,268 @@ +# NN3 (the correction test) and automatic-fail #3 (money-row immutability) + +**Status:** Draft, pending review. + +## Context + +A compliance audit against `docs/requirements/non-negotiables.md` and +`docs/project-rubrics/scoring.md`, run by three parallel agents against real code (not +documentation claims), confirmed two FAIL-level findings: + +- **NN3, the correction test** — explicitly demoed live in the debrief. `PostingService.correct()` + (the reversal+re-book mechanism) has zero production callers; the one test that exercises it + doesn't construct a genuine reversal (would double-count under the ledger's own additive-sum + balance model); and nothing republishes a statement snapshot after a restatement, so + `GET /statements/` would keep serving the stale pre-correction figure indefinitely. +- **Automatic-fail #3** — "UPDATE or DELETE on money rows. Anywhere. Ever." Six tables beyond the + core `journal_entry`/`posting` ledger permit `UPDATE` at the DB grant level and are actively + mutated by service code: `order`, `tax_lot`, `lot_consumption`, `high_water_mark`, `fee_charge`, + `approval_hold`. + +The user directed implementing only these two FAIL items (not the PARTIAL findings — bitemporal +read reach, webhook atomicity, the MCP approval UI, decision-log currency — which stay out of +scope), in one pass covering all six tables, with `settlement_obligation` explicitly left +unverified/out of scope per the user's own choice. + +This document is the design for both. Both problems turn out to share real architecture already +in this codebase — `order`'s own docstring documents it as "the rebuildable projection (ADR 7)... +`assert projection == fold(order_event)` holds," with `order_event` already correctly +append-only. The gap is that `order` itself was never given `REVOKE UPDATE` to match, and the +same "append-only facts, derived projection" shape is the house style this design replicates +across the other five tables. Likewise, NN3's real mechanism already exists — +`CustodianFileAdapter.inject_corrected_price()` (S7 §9) already posts a corrected `daily_close` +and fans `RestatementService.restate()` out to every affected customer — it just never republishes +a snapshot afterward, which is the one missing step. + +--- + +## Part 1 — NN3: the correction test + +### 1.1 What already works, verified by reading the actual code + +- `PostingService.post()`/`correct()` (`backend/app/services/ledger/posting_service.py`) — real, + DB-backed, zero-sum-validated journal-entry writer. `correct()` sets `superseded_by` on a new + entry pointing back at the one it corrects; the original row is genuinely never mutated + (confirmed: `journal_entry.superseded_by` docstring, `REVOKE UPDATE, DELETE` on both + `journal_entry` and `posting`). +- `RestatementService.restate()` (`backend/app/services/restatement/restatement_service.py`) — + already wired to four real trigger types (`RestatementTriggerType`: + `CORRECTED_CLOSE`, `LATE_DIVIDEND`, `SPLIT`, `WASH_SALE_ADJUSTMENT`, plus an unused + `MANUAL_CORRECTION`). Three call sites already exist: + `custodian_file_adapter.py:134` (a corrected closing price — this is almost certainly the + literal "a corrected price restates the affected period's return" scenario named in + `docs/requirements/project-description.md`), `wash_sale_service.py:137`, and + `corporate_action_service.py` (late dividend, split — two call sites). +- `restate()` recomputes the live `sub_period_return` rows for every window touching the affected + date, then `_relink_and_cross_check()` re-links the live TWR for any already-published period + that overlaps and calls `SnapshotService.cross_check()` on it — proving the *old* snapshot still + reproduces exactly at its *own* `publish_watermark`. This is deliberate tamper-detection (ADR + 6), not a "keep it fresh" mechanism: a published snapshot is meant to be permanently frozen, and + cross-check alarms loudly (`SnapshotCrossCheckFailedError`) if history was ever rewritten under + it. **This part must not change** — it is exactly what "the as-published figure stays queryable" + requires. + +### 1.2 The actual gap + +`_relink_and_cross_check` proves the old snapshot is still valid and stops there — it never +creates a *new* snapshot reflecting the correction. `GET /statements/` +(`backend/app/controllers/api/statements.py`) reads `published_snapshots.latest_for_period()` — a +frozen, stored row. Since nothing ever inserts a second `published_snapshot` row for an +already-published period, that endpoint keeps returning the pre-correction figure forever, even +though the live `/valuation/returns`/`/valuation/balance` endpoints (which recompute rather than +read a cached snapshot) already correctly reflect the correction on their next call. + +This is precisely the gap the frontend was already built for and is waiting on: the earlier +session's design-doc audit found `StatementList.jsx`/`StatementDetail.jsx` already implement the +"Restated" badge, the struck-through original figure, and a "View original as-published statement" +link (design-system.md §8.1) — unreachable today only because the backend condition it depends on +(`versions.length > 1`, i.e. a second `published_snapshot` row existing for the period) can never +become true. + +### 1.3 Fix — republish after a correction + +In `RestatementService._relink_and_cross_check`, after `snapshot_service.cross_check(snapshot)` +passes for a touched, already-published period, call `snapshot_service.publish(customer_id, +snapshot.period_start, snapshot.period_end)`. This creates a **new** `published_snapshot` row with +a new `publish_watermark` (Postgres's own transaction-start `now()`, per `publish()`'s existing +contract) holding the corrected figures. `PublishedSnapshotRepository.latest_for_period()` then +naturally returns the newest snapshot going forward; the original stays independently fetchable +forever via its own `publish_watermark` (the existing `?publish_watermark=` query param on +`GET /statements/`, already wired end-to-end). + +Guard against redundant snapshots: only publish again if the derived figures actually differ from +the existing latest snapshot's `twr`/`balance` (compare `SnapshotService.derive()`'s live figures, +already computed for the cross-check, against the current latest snapshot) — a restatement whose +recomputation produces no real change (e.g. `compute_twr`'s reuse-or-recompute path returning +identical numbers) should not manufacture a spurious new "restated" version. This one condition is +the only new logic beyond an additional `publish()` call. + +This single fix applies uniformly to all four trigger types — no per-trigger special-casing needed. + +### 1.4 Fix — make `correct()` itself actually correct, and give it a real caller + +The one existing test (`backend/tests/integration/test_ledger_append_only.py`) exercises +`correct()` with legs that re-book the new total (`+900/-900`) without reversing the original +(`+1000/-1000`). Since every real balance path (`ValuationService`, `SnapshotService`, +reconciliation) sums **all** postings unconditionally with no `superseded_by` filtering, by +design, a correction that doesn't include true reversal legs double-counts. Fix the test (and, if +`correct()`'s signature makes it easy to get wrong, consider having `correct()` itself compute and +post the negated original legs automatically alongside the caller's new legs, so a caller +physically cannot construct a non-reversing correction) — this makes the capability genuinely +correct regardless of whether it ever gets a production caller. + +Separately, give it one: `RestatementTriggerType.MANUAL_CORRECTION` already exists in the enum and +is unused — the scaffolding anticipates exactly this case (a staff member correcting an +erroneously-posted journal entry, as opposed to a late dividend/split/price-correction, which are +all legitimately handled by *posting a new entry*, not correcting an old one — those three don't +need `correct()` at all, and shouldn't be forced to use it). Add one minimal admin-facing service +method (e.g. on a new or existing admin service) taking `(original_journal_entry_id, new_legs, +reason)`, calling `PostingService.correct()` and then `RestatementService.restate(..., +trigger_type=MANUAL_CORRECTION)`. A full API route + frontend UI for this is out of scope unless +requested — the requirement is that the capability exists and is correct and reachable, not that +staff have a polished screen for the rare case of a genuine posting error. + +### 1.5 Fix — `curated_views.py`'s inverted filter + +`app/models/chat/curated_views.py` filters `WHERE je.superseded_by IS NULL` in three views. Given +the confirmed field semantics (`superseded_by` is set on the *new* correcting entry, pointing back; +the original's own `superseded_by` stays null forever), this filter *keeps* the stale original and +*excludes* the correction — backwards, and inconsistent with `ValuationService`'s own documented +"sum everything unconditionally, no `superseded_by` special-casing" model. Remove the filter +entirely to match, rather than inverting it (inverting would still be special-casing something the +rest of the codebase deliberately doesn't). + +### 1.6 Tests to add + +- `test_snapshot_service.py` — `publish()`, `derive()`, `cross_check()` in isolation, including the + "derive at an old watermark still reproduces the original" case and the "cross-check fails loudly + on genuine tampering" case. +- `test_restatement_service.py` — `restate()` end-to-end, including the new republish behavior and + its no-redundant-snapshot guard. +- One true end-to-end scenario test mirroring the literal demo: inject a corrected close price for + a security a customer holds and a date inside an already-published period → assert + `GET /statements/` (no watermark) now returns the corrected balance/TWR, and + `GET /statements/?publish_watermark=` still returns the untouched original, + and reconciliation still balances. +- A `correct()` unit test with genuine reversal legs, asserting the summed balance nets to the + corrected value, not the sum of both postings. +- A test for the new manual-correction entry point. + +--- + +## Part 2 — automatic-fail #3: money-row immutability + +### 2.1 The pattern, established by precedent already in this codebase + +`order` / `order_event` (ADR 7) is the house style: an append-only table of facts +(`order_event`, already `REVOKE UPDATE, DELETE`'d) plus a **derived** read — the model docstring's +own words, "the rebuildable projection... `assert projection == fold(order_event)`." The fix for +all six tables is the same shape: stop writing money/unit columns in place after creation; either +derive them at read time by folding an append-only event/adjustment log, or replace a single +mutable row with an append-only history and read the latest/aggregate. Then `REVOKE UPDATE` for +real. + +### 2.2 Table by table + +**`order`** (`quantity_requested`, `filled_quantity`, `average_fill_price`) — closest to done +already; `order_event` exists and is correctly append-only. Two write sites currently mutate +`order` directly: `order_projection_service.py:95-97` (folds `order_event` into the cached +columns — this is the one to eliminate, replacing every direct read of +`order.status`/`filled_quantity`/`average_fill_price` with a call to a new pure +`derive_order_state(events: Sequence[OrderEvent]) -> OrderState`-style function, called at read +time instead of cached at write time) and `order_service.py:136` (`order.status = +OrderStatus.APPROVED` — a genuine pre-submission transition with no corresponding event type +today). Resolution: extend `OrderEventType` to cover the pre-submission approval transition too +(e.g. `APPROVAL_REQUESTED`/`APPROVED`), so `order.status` is derived from folding events across its +*entire* lifecycle, not just from `submitted` onward as today — not the alternative of treating +`approval_hold` as the source, since not every order has a hold (only those crossing the +auto-approval threshold), so it can't universally answer "is this order approved" for orders that +skip that step entirely. This keeps one derivation rule for the whole table instead of a +pre-/post-submission split. Currently has +**zero** grant restriction at all (worse than the other five) — add `REVOKE UPDATE, DELETE` in the +same migration pass regardless of which sub-approach is chosen for the approval transition. + +**`tax_lot`** (`quantity_remaining`, `adjusted_basis`) — `quantity_remaining` derives cleanly as +`original_quantity − SUM(lot_consumption.quantity_consumed)` for the lot, no new table needed. +`adjusted_basis` needs a new append-only `tax_lot_basis_adjustment` table (lot_id, delta, reason, +source_event_id), written by `wash_sale_service.py`/`corporate_action_service.py` instead of +mutating `tax_lot.adjusted_basis` directly; derived as `original_cost_basis + SUM(deltas)`. +`REVOKE UPDATE`. + +**`lot_consumption.realized_gain_loss`** — mutated by `wash_sale_service.py:132`'s disallowed-loss +adjustment. Shares its root cause with Part 1: once wash-sale correctly posts a **ledger** +correction (§1.4) for the disallowed amount instead of mutating this column, `realized_gain_loss` +becomes a derived read (original recognized amount + any linked correcting postings) rather than a +stored mutable value. One fix serves both problems. `REVOKE UPDATE`. + +**`high_water_mark.peak_value`** — the model's own docstring calls this "the one intentional +exception to append-only." Convert from a single mutable row per account to an append-only history +(a new row per ratchet update, never mutating an existing one); current peak = `MAX(peak_value)` +or the latest row by timestamp for that account. This is the simplest of the six. `REVOKE UPDATE`. + +**`fee_charge`** (`status`, `stripe_charge_id`, `journal_entry_id` mutated in +`fee_charge_service.py`/`dunning_service.py`) — new append-only `fee_charge_event` table (same +shape as `order_event`) recording each lifecycle transition as a new row; current `status`/ +`stripe_charge_id` derived from the latest event for that charge. `REVOKE UPDATE`. + +**`approval_hold`** (`status`, `released_at`, `release_reason` mutated in +`approval_hold_service.py:46-48`) — same event-log treatment as `fee_charge`. (This codebase has a +precedent for a *constrained* single-transition-trigger `UPDATE` instead — +`settlement_obligation`/`agent_action_request` — deliberately not used here: the rubric's "anywhere, +ever" has no carve-out for a constrained update, so `approval_hold` gets the full append-only +treatment like the rest, not the trigger pattern.) + +### 2.3 Migrations + +One migration per table (or one combined migration touching all six, matching this project's +existing style of one focused migration per logical change — follow whichever convention recent +migrations in `backend/alembic/versions/` establish): the new event/adjustment tables where +needed, `REVOKE UPDATE, DELETE` (or `REVOKE UPDATE` where `DELETE` is already revoked) on all six +existing tables, and — for `order` specifically — closing the currently-wide-open grant. + +### 2.4 Read-site sweep + +Every place that currently reads a column being converted to derived (`order.status`, +`order.filled_quantity`, `order.average_fill_price`, `tax_lot.quantity_remaining`, +`tax_lot.adjusted_basis`, `lot_consumption.realized_gain_loss`, `high_water_mark.peak_value`, +`fee_charge.status`, `fee_charge.stripe_charge_id`, `approval_hold.status`) needs to switch to the +new derivation function instead. This is the largest mechanical surface of the whole change — +enumerate every call site per table during implementation (grep the exact column name), not +assumed complete by this list. + +### 2.5 Tests to add/update + +Per table: a test proving the DB grant genuinely rejects `UPDATE` under the app role (matching the +existing pattern in `test_ledger_append_only.py`), and a test proving the derivation function +produces the correct current state from a sequence of events/adjustments, including out-of-order +event arrival where that's already handled for `order_event` (`seq` is independent of processing +order, per its own docstring) and needs to hold for the new event tables too. Every existing test +that currently asserts against a mutated column (e.g. `order.filled_quantity == X` after a fill) +needs updating to assert against the derived read instead — full inventory during implementation. + +--- + +## Scope boundaries (explicit) + +**In scope:** exactly the two FAIL findings above, across all six flagged tables plus the +correction/republish mechanism, in one implementation pass. + +**Out of scope, by the user's own direction:** +- `settlement_obligation` — not verified against automatic-fail #3 by the audit; left + unverified rather than assumed. +- Every PARTIAL finding from the same audit: bitemporal read reach beyond published periods, + webhook atomicity/out-of-order handling, the MCP frontend approval UI, decision-log currency, + CD pipeline secrets, Alpaca going fully live. None of these are touched here. +- A full API route + frontend UI for the manual-correction entry point (§1.4) — the capability + must exist and be correct and reachable; a polished staff screen for it is not required by + either failing item. + +## Verification + +- `uv run pytest` (full backend suite) green, including every new/updated test above. +- `uv run ruff check` / `uv run mypy --strict app` / `uv run lint-imports` clean. +- A manual run of the literal NN3 scenario end-to-end: inject a corrected price for an + already-published period, confirm the statement endpoint shows the corrected figure while the + as-published watermark still returns the original, and reconciliation still balances. +- For automatic-fail #3: a direct grant check per table (`\dp` or an information_schema query) + confirming zero UPDATE/DELETE privilege for `trueup_app`/`trueup_worker` on all six tables, plus + a live attempt to `UPDATE` each one under the app role and confirm it's rejected. diff --git a/frontend/src/App.jsx b/frontend/src/App.jsx index ea1df53..5d6a424 100644 --- a/frontend/src/App.jsx +++ b/frontend/src/App.jsx @@ -30,9 +30,7 @@ function defaultRouteFor(status, principal) { return status === 'authenticated' ? defaultRouteForPrincipal(principal) : '/login' } -// Every route named in structure.md §2 is now real (some, per main's own dispatch, backed by a -// mock adapter rather than a live endpoint — portfolio, lots, fees, chat, admin customers, -// statement export). +// Every route in structure.md §2 is real; some are backed by a mock adapter, not a live endpoint. function AppShell() { const { status, principal } = useSession() diff --git a/frontend/src/components/Badge/Badge.jsx b/frontend/src/components/Badge/Badge.jsx index eb41c68..c8c4a80 100644 --- a/frontend/src/components/Badge/Badge.jsx +++ b/frontend/src/components/Badge/Badge.jsx @@ -1,10 +1,6 @@ import './Badge.css' -/** - * Design system §7.4. `tone="neutral"` is the provenance-disclosure treatment (§8.3 "Simulated", - * §8.8 "Provisional") — deliberately not a semantic color. Always pair with a short label word, - * never a bare color dot. - */ +/** Design system §7.4. `tone="neutral"` is non-semantic provenance-disclosure (§8.3, §8.8); pair with a label word. */ export function Badge({ tone = 'neutral', icon, className = '', children, ...rest }) { return ( diff --git a/frontend/src/components/Button/Button.jsx b/frontend/src/components/Button/Button.jsx index 54f6286..00c4217 100644 --- a/frontend/src/components/Button/Button.jsx +++ b/frontend/src/components/Button/Button.jsx @@ -1,9 +1,6 @@ import './Button.css' -/** - * Design system §7.1. `variant="danger-outline"` is the shared privileged-action trigger from - * §8.6 (order approval, break resolution, KYC override) — deliberately quieter than `primary`. - */ +/** Design system §7.1. `variant="danger-outline"` is the privileged-action trigger (§8.6). */ export function Button({ variant = 'primary', size = 'default', diff --git a/frontend/src/components/EmptyState/EmptyState.jsx b/frontend/src/components/EmptyState/EmptyState.jsx index aa77441..13b28eb 100644 --- a/frontend/src/components/EmptyState/EmptyState.jsx +++ b/frontend/src/components/EmptyState/EmptyState.jsx @@ -1,10 +1,6 @@ import './EmptyState.css' -/** - * Design system §7.5. `variant="good"` is for a genuinely desired empty state ("No open breaks") — - * gets a success-tinted checkmark instead of the neutral default icon, so it isn't mistaken for a - * loading artifact (`structure.md` §6). - */ +/** Design system §7.5. `variant="good"` marks a desired empty state (e.g. no open breaks) with a success checkmark. */ export function EmptyState({ variant = 'neutral', title, description, action }) { return (
diff --git a/frontend/src/components/Icon/Icon.css b/frontend/src/components/Icon/Icon.css new file mode 100644 index 0000000..570dc0f --- /dev/null +++ b/frontend/src/components/Icon/Icon.css @@ -0,0 +1,24 @@ +.tu-icon { + fill: none; + stroke: currentColor; + stroke-width: 1.5; + stroke-linecap: round; + stroke-linejoin: round; + flex: none; + display: inline-block; +} + +.tu-icon--sm { + width: var(--icon-size-sm); + height: var(--icon-size-sm); +} + +.tu-icon--md { + width: var(--icon-size-md); + height: var(--icon-size-md); +} + +.tu-icon--lg { + width: var(--icon-size-lg); + height: var(--icon-size-lg); +} diff --git a/frontend/src/components/Icon/Icon.jsx b/frontend/src/components/Icon/Icon.jsx new file mode 100644 index 0000000..7210dbe --- /dev/null +++ b/frontend/src/components/Icon/Icon.jsx @@ -0,0 +1,32 @@ +import './Icon.css' +import { ICON_PATHS } from './paths.js' + +/** + * A single glyph from the app's icon set (`paths.js`), 16x16, `currentColor`-driven so it inherits + * the theme automatically. `aria-hidden` by default -- icons are almost always paired with visible + * text per design-system.md §2.4's never-color-alone rule, so they carry no accessible name of + * their own. Pass `label` only for the rare icon-only control (e.g. a bare dismiss button) where + * the icon IS the only content; it swaps `aria-hidden` for a real accessible name. + */ +export function Icon({ name, size = 'md', label, className = '', ...rest }) { + const d = ICON_PATHS[name] + if (!d) return null + + const sizeClass = size === 'sm' ? 'tu-icon--sm' : size === 'lg' ? 'tu-icon--lg' : 'tu-icon--md' + + return ( + + {d.map((segment) => ( + + ))} + + ) +} diff --git a/frontend/src/components/Icon/index.js b/frontend/src/components/Icon/index.js new file mode 100644 index 0000000..810e4b8 --- /dev/null +++ b/frontend/src/components/Icon/index.js @@ -0,0 +1 @@ +export { Icon } from './Icon.jsx' diff --git a/frontend/src/components/Icon/paths.js b/frontend/src/components/Icon/paths.js new file mode 100644 index 0000000..50327f9 --- /dev/null +++ b/frontend/src/components/Icon/paths.js @@ -0,0 +1,30 @@ +/** + * Icon path data, 16x16 viewBox. Each entry is an array of `d` strings (one per entry) -- + * no presentation attributes here; stroke/fill live in Icon.css so every glyph inherits the theme + * via currentColor for free. Named export keeps this tree-shakeable; Icon.jsx looks these up by + * string name for a small, reviewable API. + */ + +export const ICON_PATHS = { + 'chevron-down': ['M4 6.5 8 10.5 12 6.5'], + 'chevron-up': ['M4 9.5 8 5.5 12 9.5'], + 'chevron-left': ['M9.5 4 5.5 8 9.5 12'], + 'chevron-right': ['M6.5 4 10.5 8 6.5 12'], + 'alert-triangle': ['M8 2.5 14.5 13.5h-13z', 'M8 6.5v3.2', 'M8 11.9v.1'], + 'alert-circle': ['M8 8m-6 0a6 6 0 1 0 12 0a6 6 0 1 0 -12 0', 'M8 5v3.5', 'M8 11v.1'], + 'check-circle': ['M8 8m-6 0a6 6 0 1 0 12 0a6 6 0 1 0 -12 0', 'M5.2 8.2 7.2 10 10.8 6'], + 'info-circle': ['M8 8m-6 0a6 6 0 1 0 12 0a6 6 0 1 0 -12 0', 'M8 7.2v3.3', 'M8 5v.1'], + x: ['M4.5 4.5 11.5 11.5', 'M11.5 4.5 4.5 11.5'], + search: ['M7 7m-4.2 0a4.2 4.2 0 1 0 8.4 0a4.2 4.2 0 1 0 -8.4 0', 'M10 10 13 13'], + 'external-link': ['M6.5 4.5H11.5V9.5', 'M11.5 4.5 5 11'], + download: ['M8 2.5v7.2', 'M5 7 8 9.7 11 7', 'M3 12.5h10'], + 'arrow-left': ['M12.5 8h-9', 'M6.5 4 3 8l3.5 4'], + send: ['M13.5 2.5 2.5 7.2l4.6 1.8 1.8 4.6z', 'M7.1 9 13.5 2.5'], + refresh: [ + 'M3.2 8a4.8 4.8 0 0 1 8-3.4l1 1', + 'M12.2 3v2.8h-2.8', + 'M12.8 8a4.8 4.8 0 0 1-8 3.4l-1-1', + 'M3.8 13v-2.8h2.8', + ], + menu: ['M2.5 4.5h11', 'M2.5 8h11', 'M2.5 11.5h11'], +} diff --git a/frontend/src/components/SimulatedBadge/SimulatedBadge.jsx b/frontend/src/components/SimulatedBadge/SimulatedBadge.jsx index 177a09a..8271f0e 100644 --- a/frontend/src/components/SimulatedBadge/SimulatedBadge.jsx +++ b/frontend/src/components/SimulatedBadge/SimulatedBadge.jsx @@ -1,11 +1,6 @@ import { Badge } from '../Badge' -/** - * Design system §8.3's provenance-disclosure pattern, generalized past its one named case - * (simulated account approval): a neutral, non-semantic tag marking a screen or section as backed - * by mock data rather than a live backend route — never a health signal, so never a semantic - * color (rubric: "honest real-versus-simulated labelling"). - */ +/** Design system §8.3. Marks a screen/section as backed by mock data, not a live route. */ export function SimulatedBadge({ className }) { return ( diff --git a/frontend/src/components/Skeleton/Skeleton.jsx b/frontend/src/components/Skeleton/Skeleton.jsx index f0a7611..7a6df9e 100644 --- a/frontend/src/components/Skeleton/Skeleton.jsx +++ b/frontend/src/components/Skeleton/Skeleton.jsx @@ -1,9 +1,6 @@ import './Skeleton.css' -/** - * Design system §7.7. A block the shape/size of the content it replaces — callers size it per - * screen region (`structure.md` §6 names a specific skeleton shape per screen, never a bare spinner). - */ +/** Design system §7.7. Sized per screen region by the caller; never a bare spinner (structure.md §6). */ export function Skeleton({ width = '100%', height = '1em', radius, className = '', style, ...rest }) { return ( diff --git a/frontend/src/components/Table/Table.jsx b/frontend/src/components/Table/Table.jsx index 09c26fc..96c3f40 100644 --- a/frontend/src/components/Table/Table.jsx +++ b/frontend/src/components/Table/Table.jsx @@ -1,9 +1,6 @@ import './Table.css' -/** - * Design system §7.6. Composed as `……`. `stickyHeader` is meant - * for tables over ~10 visible rows (Transactions, Lots); `striped` is opt-in for dense tables only. - */ +/** Design system §7.6. `stickyHeader` for tables >~10 rows; `striped` opt-in for dense tables. */ export function Table({ striped = false, stickyHeader = false, className = '', children, ...rest }) { const classes = [ 'tu-table', diff --git a/frontend/src/components/Toast/Toast.jsx b/frontend/src/components/Toast/Toast.jsx index 8639c61..545e454 100644 --- a/frontend/src/components/Toast/Toast.jsx +++ b/frontend/src/components/Toast/Toast.jsx @@ -5,10 +5,7 @@ const ToastContext = createContext(undefined) let nextToastId = 0 -/** - * Design system §7.8. Reserved for transient confirmations — a state that must persist (a bounced - * deposit, per `structure.md` §6) belongs in a row/banner instead, since a toast can be missed. - */ +/** Design system §7.8. Transient confirmations only — persistent state belongs in a row/banner (structure.md §6). */ export function ToastProvider({ children }) { const [toasts, setToasts] = useState([]) const timers = useRef(new Map()) diff --git a/frontend/src/features/admin-breaks/components/AgingIndicator.jsx b/frontend/src/features/admin-breaks/components/AgingIndicator.jsx index 6c4fcac..a5806df 100644 --- a/frontend/src/features/admin-breaks/components/AgingIndicator.jsx +++ b/frontend/src/features/admin-breaks/components/AgingIndicator.jsx @@ -2,11 +2,7 @@ import './AgingIndicator.css' const SECONDS_PER_DAY = 86400 -/** - * Design system §8.4: escalates through the semantic scale by age, each step paired with a label - * so color alone never carries the meaning — `< 1 day` (mild warning tint), `1–3 days` (full - * warning), `> 3 days` (full error). - */ +/** Design system §8.4 age-escalation tiers. */ export function AgingIndicator({ ageSeconds }) { const days = ageSeconds / SECONDS_PER_DAY let tier = 'mild' diff --git a/frontend/src/features/admin-breaks/components/BreakQueue.jsx b/frontend/src/features/admin-breaks/components/BreakQueue.jsx index d43000a..f3484e4 100644 --- a/frontend/src/features/admin-breaks/components/BreakQueue.jsx +++ b/frontend/src/features/admin-breaks/components/BreakQueue.jsx @@ -26,7 +26,7 @@ export function BreakQueue() { } if (breaks.length === 0) { - // A real, good state (design-system §7.5) — not a blank-looking placeholder. + // Design system §7.5 good-state. return } diff --git a/frontend/src/features/admin-breaks/components/BreakRow.jsx b/frontend/src/features/admin-breaks/components/BreakRow.jsx index 64dfe13..42e2321 100644 --- a/frontend/src/features/admin-breaks/components/BreakRow.jsx +++ b/frontend/src/features/admin-breaks/components/BreakRow.jsx @@ -13,7 +13,7 @@ export function BreakRow({ breakRow, onClick }) { return ( {breakRow.break_type} - {/* `customer_id` is nullable (S7 §5.2) — a malformed file row with no single-customer attribution. */} + {/* customer_id nullable (S7 §5.2). */} {breakRow.customer_id ? breakRow.customer_id.slice(0, 8) : 'Unattributed'} {previewJson(breakRow.expected)} {previewJson(breakRow.actual)} diff --git a/frontend/src/features/admin-breaks/components/ResolveForm.jsx b/frontend/src/features/admin-breaks/components/ResolveForm.jsx index ff75a37..dae1f02 100644 --- a/frontend/src/features/admin-breaks/components/ResolveForm.jsx +++ b/frontend/src/features/admin-breaks/components/ResolveForm.jsx @@ -5,7 +5,7 @@ import { getErrorMessage } from '../../../utils/apiErrorMessage.js' import { useResolveBreak } from '../hooks/useResolveBreak.js' import './ResolveForm.css' -/** Design system §8.6's shared privileged-action pattern, applied to break resolution. */ +/** Design system §8.6 privileged-action pattern. */ export function ResolveForm({ breakId, onResolved }) { const { status, error, resolve } = useResolveBreak() const [note, setNote] = useState('') diff --git a/frontend/src/features/admin-breaks/hooks/useBreaks.js b/frontend/src/features/admin-breaks/hooks/useBreaks.js index 3fae631..63119ae 100644 --- a/frontend/src/features/admin-breaks/hooks/useBreaks.js +++ b/frontend/src/features/admin-breaks/hooks/useBreaks.js @@ -3,7 +3,7 @@ import { adminBreaksApi } from '../api/adminBreaksApi.js' const IDLE = { status: 'idle', breaks: [], error: null } -/** `GET /admin/breaks?status=open` — sorted oldest-first by the backend (S7 §7). */ +/** GET /admin/breaks?status=open, sorted oldest-first (S7 §7). */ export function useBreaks() { const [state, setState] = useState(IDLE) diff --git a/frontend/src/features/admin-customers/api/adminCustomersApi.js b/frontend/src/features/admin-customers/api/adminCustomersApi.js index ab1c876..f888c13 100644 --- a/frontend/src/features/admin-customers/api/adminCustomersApi.js +++ b/frontend/src/features/admin-customers/api/adminCustomersApi.js @@ -1,8 +1,4 @@ -// MOCK — no backend endpoint exists yet for the admin customer directory/detail/KYC-override -// (S8's still-missing GET /admin/customers, GET /admin/customers/, POST -// /admin/kyc-overrides/). The fee panel on the customer-detail page is wired for -// real separately (see `feesApi.getForCustomer`, used by `useCustomerFees`) since -// `GET /fees?customer_id=` already exists. +// MOCK — no backend endpoint exists yet (S8). Replace with a real fetch call once that spec ships. import { mockClient } from '../../../services/mockClient.js' const NAMESPACE = 'admin-customers' diff --git a/frontend/src/features/admin-customers/components/KycOverrideForm.jsx b/frontend/src/features/admin-customers/components/KycOverrideForm.jsx index 0483685..c17ca93 100644 --- a/frontend/src/features/admin-customers/components/KycOverrideForm.jsx +++ b/frontend/src/features/admin-customers/components/KycOverrideForm.jsx @@ -5,7 +5,7 @@ import { getErrorMessage } from '../../../utils/apiErrorMessage.js' import { useKycOverride } from '../hooks/useKycOverride.js' import './KycOverrideForm.css' -/** Design system §8.6: reopening a locked-`rejected` KYC status is a privileged, audited override. */ +/** Design system §8.6 privileged-action pattern. */ export function KycOverrideForm({ customer, onOverridden }) { const { status, error, submit } = useKycOverride() const [confirming, setConfirming] = useState(false) diff --git a/frontend/src/features/admin-customers/components/OpenBreakCallout.jsx b/frontend/src/features/admin-customers/components/OpenBreakCallout.jsx index d29d9e9..c22f9b2 100644 --- a/frontend/src/features/admin-customers/components/OpenBreakCallout.jsx +++ b/frontend/src/features/admin-customers/components/OpenBreakCallout.jsx @@ -1,7 +1,7 @@ import { Link } from 'react-router-dom' import './OpenBreakCallout.css' -/** Design system §8.4: always renders at error weight regardless of the break's own age-tier — surfaced regardless of which tab is active. */ +/** Design system §8.4, always error weight. */ export function OpenBreakCallout() { return (
diff --git a/frontend/src/features/admin-customers/hooks/useCustomerSearch.js b/frontend/src/features/admin-customers/hooks/useCustomerSearch.js index 3ea3994..12c8ddd 100644 --- a/frontend/src/features/admin-customers/hooks/useCustomerSearch.js +++ b/frontend/src/features/admin-customers/hooks/useCustomerSearch.js @@ -3,7 +3,7 @@ import { adminCustomersApi } from '../api/adminCustomersApi.js' const IDLE = { status: 'idle', query: '', results: [], error: null } -/** `status: 'idle'` means no query has been submitted yet — distinct from a submitted, empty-result search. */ +/** idle = no query submitted yet, distinct from an empty result. */ export function useCustomerSearch() { const [state, setState] = useState(IDLE) diff --git a/frontend/src/features/auth/api/authApi.js b/frontend/src/features/auth/api/authApi.js index cfc7210..48b5d93 100644 --- a/frontend/src/features/auth/api/authApi.js +++ b/frontend/src/features/auth/api/authApi.js @@ -2,9 +2,7 @@ import { apiClient } from '../../../services/apiClient.js' export const authApi = { register: (payload) => apiClient.post('/auth/register', payload), - // Returns either a fully-authenticated AuthResponse, or a MfaPendingResponse - // ({ mfa_pending: true, csrf_token }) for a staff/adviser account — both shapes carry - // `mfa_pending`, so callers branch on that field alone. + // Returns AuthResponse or MfaPendingResponse; callers branch on `mfa_pending`. login: (payload) => apiClient.post('/auth/login', payload), verifyMfa: (payload) => apiClient.post('/auth/mfa/verify', payload), logout: () => apiClient.post('/auth/logout'), diff --git a/frontend/src/features/auth/components/AuthForm.css b/frontend/src/features/auth/components/AuthForm.css index e9af2ea..d47f1ce 100644 --- a/frontend/src/features/auth/components/AuthForm.css +++ b/frontend/src/features/auth/components/AuthForm.css @@ -46,3 +46,42 @@ .tu-auth-form__footer a { color: var(--color-accent); } + +.tu-password-rules { + display: flex; + flex-direction: column; + gap: var(--space-1); + margin-top: var(--space-1); + padding: 0; + list-style: none; +} + +.tu-password-rules__item { + display: flex; + align-items: center; + gap: var(--space-2); + font-size: var(--font-size-caption); + line-height: var(--line-height-caption); + color: var(--color-text-muted); +} + +.tu-password-rules__item--met { + color: var(--color-success); +} + +.tu-password-rules__icon { + flex-shrink: 0; + color: currentColor; +} + +.tu-visually-hidden { + position: absolute; + width: 1px; + height: 1px; + padding: 0; + margin: -1px; + overflow: hidden; + clip: rect(0, 0, 0, 0); + white-space: nowrap; + border: 0; +} diff --git a/frontend/src/features/auth/components/LoginForm.jsx b/frontend/src/features/auth/components/LoginForm.jsx index 9a4baec..4b2e97d 100644 --- a/frontend/src/features/auth/components/LoginForm.jsx +++ b/frontend/src/features/auth/components/LoginForm.jsx @@ -4,11 +4,15 @@ import { Button } from '../../../components/Button' import { Input } from '../../../components/Input' import { getErrorMessage } from '../../../utils/apiErrorMessage.js' import { useLogin } from '../hooks/useLogin.js' +import { validateEmail, validateMfaCode } from '../validation.js' import './AuthForm.css' const MFA_STATUSES = new Set(['mfa_required', 'submitting_mfa', 'mfa_error']) const SUBMITTING_STATUSES = new Set(['submitting', 'submitting_mfa']) +const EMAIL_ID = 'login-email' +const CODE_ID = 'login-mfa-code' + export function LoginForm() { const { status, error, login, verifyMfa } = useLogin() const navigate = useNavigate() @@ -16,27 +20,59 @@ export function LoginForm() { const [password, setPassword] = useState('') const [remember, setRemember] = useState(false) const [code, setCode] = useState('') + const [emailTouched, setEmailTouched] = useState(false) + const [emailError, setEmailError] = useState(null) + const [codeError, setCodeError] = useState(null) const isMfaStep = MFA_STATUSES.has(status) const isSubmitting = SUBMITTING_STATUSES.has(status) + const handleEmailBlur = () => { + setEmailTouched(true) + setEmailError(validateEmail(email)) + } + + const handleEmailChange = (event) => { + const nextValue = event.target.value + setEmail(nextValue) + if (emailTouched) setEmailError(validateEmail(nextValue)) + } + if (isMfaStep) { return ( -
{ - event.preventDefault() - verifyMfa(code) - .then(() => navigate('/')) - .catch(() => {}) - }}> + { + event.preventDefault() + const message = validateMfaCode(code) + setCodeError(message) + if (message) { + document.getElementById(CODE_ID)?.focus() + return + } + verifyMfa(code) + .then(() => navigate('/')) + .catch(() => {}) + }} + >

Enter your verification code

Open your authenticator app and enter the current code.

setCode(event.target.value)} + onChange={(event) => { + const nextValue = event.target.value + setCode(nextValue) + if (codeError) setCodeError(validateMfaCode(nextValue)) + }} + onBlur={() => setCodeError(validateMfaCode(code))} + error={codeError} required /> {status === 'mfa_error' && ( @@ -54,8 +90,16 @@ export function LoginForm() { return ( { event.preventDefault() + const message = validateEmail(email) + setEmailError(message) + setEmailTouched(true) + if (message) { + document.getElementById(EMAIL_ID)?.focus() + return + } login({ email, password, remember }) .then((result) => { if (!result.mfaRequired) navigate('/') @@ -68,11 +112,17 @@ export function LoginForm() { label="Email" type="email" name="email" + id={EMAIL_ID} autoComplete="email" value={email} - onChange={(event) => setEmail(event.target.value)} + onChange={handleEmailChange} + onBlur={handleEmailBlur} + error={emailError} required /> + {/* Presence-only, deliberately: a login form must never reject a real, older, + already-provisioned password because a newer strength policy exists. Do not add a + strength/format rule here — that belongs on signup only (see validation.js). */} validateEmail(values.email), + password: (values) => validatePassword(values.password), + confirmPassword: (values) => validatePasswordConfirmation(values.password, values.confirmPassword), +} + +const FIELD_FOCUS_IDS = { + email: EMAIL_ID, + password: PASSWORD_ID, + confirmPassword: CONFIRM_PASSWORD_ID, +} + export function RegisterForm() { const { status, error, register } = useRegister() const navigate = useNavigate() @@ -14,16 +37,57 @@ export function RegisterForm() { const [email, setEmail] = useState('') const [password, setPassword] = useState('') const [confirmPassword, setConfirmPassword] = useState('') - const [validationMessage, setValidationMessage] = useState(null) + const [touched, setTouched] = useState({}) + const [fieldErrors, setFieldErrors] = useState({}) const isSubmitting = status === 'submitting' + const values = { email, password, confirmPassword } + const strength = describePassword(password) + // Input's own aria-describedby (wired to its inline error message, id `${id}-message`) would be + // clobbered by ours below since {...rest} is spread after it — so reconstruct both ids here + // rather than losing the error announcement while the strength checklist is attached. + const passwordDescribedBy = [PASSWORD_RULES_ID, fieldErrors.password ? `${PASSWORD_ID}-message` : null] + .filter(Boolean) + .join(' ') + + const runValidator = (field, nextValues) => FIELD_VALIDATORS[field](nextValues) + + const validateField = (field, nextValues = values) => { + const message = runValidator(field, nextValues) + setFieldErrors((prev) => ({ ...prev, [field]: message })) + return message + } + + const handleBlur = (field) => () => { + setTouched((prev) => ({ ...prev, [field]: true })) + validateField(field) + } + + const handleChange = (field, setter) => (event) => { + const nextValue = event.target.value + setter(nextValue) + const nextValues = { ...values, [field]: nextValue } + // Re-validate live once a field has already been touched, so a fixed error clears + // immediately instead of waiting for the next blur; confirm-password also re-checks live + // once the password itself changes, since a match can break without confirm being edited. + if (touched[field]) validateField(field, nextValues) + if (field === 'password' && touched.confirmPassword) validateField('confirmPassword', nextValues) + if (field === 'confirmPassword' && nextValue.length > 0 && password.length > 0) { + validateField('confirmPassword', nextValues) + } + } const handleSubmit = async (event) => { event.preventDefault() - setValidationMessage(null) - if (password !== confirmPassword) { - setValidationMessage('Passwords do not match.') + const fields = ['email', 'password', 'confirmPassword'] + const errors = Object.fromEntries(fields.map((field) => [field, runValidator(field, values)])) + setFieldErrors(errors) + setTouched({ email: true, password: true, confirmPassword: true }) + + const firstInvalid = fields.find((field) => errors[field]) + if (firstInvalid) { + document.getElementById(FIELD_FOCUS_IDS[firstInvalid])?.focus() return } @@ -32,49 +96,70 @@ export function RegisterForm() { showToast({ message: 'Account created — log in to continue.', tone: 'success' }) navigate('/login') } catch { - // surfaced below via `error`/`status` + // surfaced below via `error`/`status`; input state is left untouched so the user can retry } } - const displayError = - validationMessage || - (status === 'error' ? getErrorMessage(error, 'Registration failed — this email may already be registered.') : null) + const serverErrorMessage = + status === 'error' ? getErrorMessage(error, 'Registration failed — this email may already be registered.') : null return ( - +

Create your account

setEmail(event.target.value)} - required - /> - setPassword(event.target.value)} - minLength={8} - hint="At least 8 characters." + onChange={handleChange('email', setEmail)} + onBlur={handleBlur('email')} + error={fieldErrors.email} required /> +
+ +
    +
  • + + At least 8 characters + {strength.hasMinLength ? ' — met' : ' — not met'} +
    • +
  • + + 12+ characters, or a mix of 3+ of: lowercase, uppercase, number, symbol + {strength.hasStrength ? ' — met' : ' — not met'} +
    • +
+
setConfirmPassword(event.target.value)} + onChange={handleChange('confirmPassword', setConfirmPassword)} + onBlur={handleBlur('confirmPassword')} + error={fieldErrors.confirmPassword} required /> - {displayError && ( + {serverErrorMessage && (

- {displayError} + {serverErrorMessage}

)}