Merge remote-tracking branch 'origin/main' into codex/whe-31-adapters

# Conflicts:
#	tsconfig.json

docs/runbooks/e2e-tests.md

@@ -0,0 +1,66 @@
+# End-to-End Smoke Tests
+
+## Overview
+
+The `scripts/e2e/billing-flow.ts` script runs a deterministic end-to-end
+smoke test for the billing pipeline. It exercises:
+
+- Purchase ingestion from a simulated topic message
+- Utility bill entry via bot commands
+- Monthly statement generation and balance verification
+
+## Prerequisites
+
+- Bun 1.3+ installed
+- A running Supabase/Postgres database with the schema applied
+- `DATABASE_URL` set (via `.env` or environment)
+- `E2E_SMOKE_ALLOW_WRITE=true` set explicitly (safety guard)
+
+## Running locally
+
+```bash
+# 1. Ensure .env has a valid DATABASE_URL
+cp .env.example .env
+# edit .env with real DATABASE_URL
+
+# 2. Apply database migrations
+bun run db:migrate
+
+# 3. Run the e2e smoke test
+E2E_SMOKE_ALLOW_WRITE=true bun run test:e2e
+```
+
+The test seeds its own data (household + 3 roommates), runs the full
+purchase → utility → statement flow, asserts deterministic totals, and
+cleans up after itself.
+
+## Expected output
+
+On success:
+
+```text
+E2E smoke passed: purchase ingestion, utility updates, and statements are deterministic
+```
+
+On failure the script exits with code 1 and prints the assertion error.
+
+## CI integration
+
+Run the e2e smoke test with `bun run test:e2e` locally or in a dedicated
+CI job. If you wire it into CI, gate it on `DATABASE_URL` and
+`E2E_SMOKE_ALLOW_WRITE` to avoid false failures. The test is **not**
+part of the standard CI quality matrix by default.
+
+## Test data
+
+The test creates temporary records with random UUIDs:
+
+| Entity    | Details                    |
+| --------- | -------------------------- |
+| Household | "E2E Smoke Household"      |
+| Alice     | Admin, telegram ID 900001  |
+| Bob       | Member, telegram ID 900002 |
+| Carol     | Member, telegram ID 900003 |
+
+All test data is cleaned up in a `finally` block via cascade delete on
+the household row.

docs/runbooks/iac-terraform.md

@@ -18,7 +18,7 @@ gcloud auth application-default login
 
 ```bash
 cp infra/terraform/terraform.tfvars.example infra/terraform/terraform.tfvars
-terraform -chdir=infra/terraform init
+terraform -chdir=infra/terraform init -backend-config="bucket=<terraform-state-bucket>"
 terraform -chdir=infra/terraform plan
 terraform -chdir=infra/terraform apply
 ```
@@ -35,10 +35,21 @@ bun run infra:validate
 After first apply, add secret versions:
 
 ```bash
+echo -n "<telegram-bot-token>" | gcloud secrets versions add telegram-bot-token --data-file=- --project <project_id>
 echo -n "<telegram-webhook-secret>" | gcloud secrets versions add telegram-webhook-secret --data-file=- --project <project_id>
 echo -n "<scheduler-shared-secret>" | gcloud secrets versions add scheduler-shared-secret --data-file=- --project <project_id>
 ```
 
+If you set optional secret IDs such as `database_url_secret_id` or
+`openai_api_key_secret_id`, add versions for those secrets too.
+
+Keep bot runtime config that is not secret in your `*.tfvars` file:
+
+- `bot_household_id`
+- `bot_household_chat_id`
+- `bot_purchase_topic_id`
+- optional `bot_parser_model`
+
 ## Environment strategy
 
 - Keep separate states for `dev` and `prod`.

docs/specs/HOUSEBOT-061-local-e2e-smoke-tests.md

@@ -0,0 +1,77 @@
+# HOUSEBOT-061: Local End-to-End Smoke Tests for Billing Flow
+
+## Summary
+
+Add a pragmatic local smoke test that exercises the main billing path against a real database with deterministic assertions.
+
+## Goals
+
+- Provide `bun run test:e2e` for local pre-deploy confidence.
+- Cover purchase ingestion, manual utility entry, and statement generation in one flow.
+- Ensure smoke data is isolated and cleaned up automatically.
+
+## Non-goals
+
+- Full browser or Telegram API end-to-end automation.
+- Running destructive write tests in the default CI quality matrix.
+- Comprehensive scenario coverage for every finance edge case.
+
+## Scope
+
+- In: write-gated smoke script, docs, typed env for the smoke test, deterministic assertions, cleanup.
+- Out: full staging environment orchestration.
+
+## Interfaces and Contracts
+
+- Command: `bun run test:e2e`
+- Required env:
+  - `DATABASE_URL`
+  - `E2E_SMOKE_ALLOW_WRITE=true`
+- Script behavior:
+  - creates temporary household/member/cycle data
+  - simulates Telegram topic purchase ingestion
+  - simulates finance commands for rent, utilities, and statements
+  - deletes created data in `finally`
+
+## Domain Rules
+
+- Use integer minor units only.
+- Statement totals must match deterministic settlement behavior.
+- Purchase-topic ingestion must not swallow non-purchase slash commands.
+
+## Data Model Changes
+
+- None.
+
+## Security and Privacy
+
+- Test writes are disabled unless `E2E_SMOKE_ALLOW_WRITE=true`.
+- No production secrets are logged by the smoke script.
+
+## Observability
+
+- Script prints a single success line on pass.
+- Failures surface assertion or runtime errors with non-zero exit code.
+
+## Edge Cases and Failure Modes
+
+- Missing `DATABASE_URL`: fail fast in env validation.
+- Missing explicit write guard: fail fast before DB writes.
+- Middleware ordering regression: smoke test should fail when commands stop emitting statements.
+
+## Test Plan
+
+- Unit: parser/topic candidate tests cover slash-command exclusion.
+- Integration: `bun run test:e2e` against a migrated dev database.
+- E2E: same smoke script verifies purchase ingestion -> statement -> recalculated statement after utility update.
+
+## Acceptance Criteria
+
+- [ ] `bun run test:e2e` executes locally with deterministic output.
+- [ ] Purchase ingestion and utility updates are both covered in the same smoke flow.
+- [ ] Docs explain required env and safety guard.
+
+## Rollout Plan
+
+- Keep the smoke test local-first.
+- Consider adding an opt-in CI job later once a dedicated disposable database is available.