feat: semchunk sidecar + AWS environment blueprint + quick-start (v1.57.0 → v1.59.0)

[johntooth]

Phase summary

Three phases on this branch:

v1.57.0 — opt-in semchunk sidecar + AWS IaC (ADR-030 executed, ADR-033). A new IChunker domain port injected into DocumentIndexingService; CHUNKER_PROVIDER=semchunk routes chunking through a Python FastAPI sidecar (services/semchunk/) with automatic, logged fallback to the existing fixed-window chunker — indexing degrades rather than fails; unset means byte-identical behaviour to before. New indexing only (corpus re-chunk stays deferred per ADR-030 Decision 2). Plus a production Dockerfile.web and a compose profile.

v1.58.0 — AWS environment blueprint (ADR-034). infra/aws became a two-layer blueprint so third parties can stamp Wayfinder environments on demand: core/ (apply once — VPC, ECS cluster + Service Connect namespace, shared RDS Postgres 16, ALB with wildcard HTTPS listener, ECR) and environments/ (one Terraform workspace per stamp — own database via cyrilgdn/postgresql, own S3 bucket/secrets/IAM, web service + https://<env>.<base_domain> host rule, optional per-env semchunk sidecar). scripts/new-environment.sh / destroy-environment.sh + optional workflow_dispatch workflow. Breaking for v1.57.0 infra adopters (flat layout removed; destroy-before-adopt documented).

v1.59.0 — quick-start (ADR-035). Setup for a cloud engineer collapsed to three commands:

./scripts/bootstrap.sh --region … --state-bucket … --base-domain … --route53-zone-id …
./scripts/db-tunnel.sh &
./scripts/new-environment.sh dev --via-tunnel

• bootstrap.sh: idempotent preflight → state bucket → config generation → core apply → image build/push
• core issues the wildcard ACM cert itself when a Route53 zone is given (certificate_arn now optional, plan-time guard requires one of the two)
• default-on SSM bastion (t4g.nano, SSM-only, IMDSv2, ≈$4/mo, enable_bastion=false to remove) + db-tunnel.sh + --via-tunnel on stamp/destroy — removes the RDS network-path footgun; overrides redirect only the terraform provider, the stamped DATABASE_URL keeps the in-VPC host
• environments inherit route53_zone_id from core

Files changed

• App (v1.57.0): packages/domain/src/ports/chunker.ts; packages/adapters/src/extraction/{fixed-window,semchunk,fallback}-chunker.ts (+tests); indexing-service chunker injection; apps/web/src/lib/{env,container}.ts; services/semchunk/; docker-compose.yml; Dockerfile.web; .env.example
• Infra (v1.58–59): infra/aws/{core,environments}/, modules network/database-server/cluster/environment/semchunk-service, scripts/{bootstrap,db-tunnel,new-environment,destroy-environment}.sh, backend.hcl.example; .github/workflows/provision-environment.yml
• Repo: validate.sh check 16 (guarded terraform fmt/validate over both roots); PRD §10a; ADR-030/033/034/035; phase docs + summaries under implemented/v1.57.0–v1.59.0

Version bump

MINOR ×3 — 1.56.0 → 1.59.0 (VERSION + root package.json in sync; no DB schema changes in any phase).

Test coverage

• Unit: 4 new adapter test files + extended indexing tests; ./validate.sh green after every phase (15 PASS, 0 FAIL)
• Sidecar: 8 pytest contract tests, also executed during the image build
• E2E: apps/web/e2e/phase-semchunk-sidecar.spec.ts — 4/4 passed against a live sidecar during the build
• Scripts (documented e2e deviation — no in-repo runtime surface for IaC): all four scripts exercised directly — usage/exit codes, name validation, missing-binary/credentials/cert-or-zone errors, --via-tunnel parsing incl. invalid ports, tunnel-not-listening fail-fast

Notes for review

• Terraform could not execute in the build sandbox (network policy): run terraform -chdir=infra/aws/core init -backend=false && terraform -chdir=infra/aws/core validate (same for environments/) before applying.
• db-tunnel.sh assumes the AWS Session Manager plugin is installed.
• Cert auto-issuance hangs if the hosted zone doesn't serve the domain's NS records (bootstrap prints a hint first).

🤖 Generated with Claude Code

https://claude.ai/code/session_01WR73cFcTm6JKJfGckK8JNa