docs planning history P01_FOUNDATION_EVIDENCE - AlexandreZanata/Abastevo GitHub Wiki

Archived P01 foundation evidence

Preserved verbatim below from PROGRESS at repository commit 3540011eab38e1287ef344bdd9d457d9caae2606. Historical claims of an unborn branch, no commits/push, outstanding initial toolchain blockers or a closed gate awaiting CI are superseded by the current PROGRESS header. Prior command outcomes are reported evidence, not rerun during the delivery-plan adjustment.

Current execution state

  • Updated: 2026-09-28.
  • Phase: P01 foundations COMPLETE — gate G01 CLOSED (CI green on both workflows).
  • Current task: P02-T01 — Shared ANP fixtures (NOT STARTED).
  • Branch observed: main, unborn (no commits). Existing origin: [email protected]:AlexandreZanata/brazil-fuel-prices.git.
  • Imported upstream: b8a52049e0294cd2d07612cedcc52b3017c5271e from brazil-fuel-prices-app.
  • P01-T01 evidence: new docs/backend/TOOLCHAIN.md (D01: Go ≥1.26/preferred 1.27.x; PG18 + PostGIS 3.6.x; Docker 29.1.3/Compose v2.27.0; installed go1.22.2 out of support, plan-only); scoped A01/A02/A11 prose fixes in docs/architecture.md and README.md; docs/planning/BASELINE_VALIDATION.md re-validation appendix.
  • P01-T01 validation (exact): bash scripts/validate-repo-baseline.sh exit 0; full Gradle baseline BUILD SUCCESSFUL ~1m55s (81 executed/2 cached/5 up-to-date); JDK 17.0.19 auto-provisioned by Gradle; SDK 35 present at $ANDROID_HOME (prior "no platforms" note inspected the wrong path); git diff --check clean. Instrumentation/coverage/lint/live-ANP not executed.
  • Runtime blockers: Go ≥1.26 install/pin before P01-T02; Postgres/PostGIS digest pin in P01-T07. No infrastructure credentials or deployed backend.
  • Decisions: adopted architecture in ADR-004…012; version/geocoder/parser/privacy/recovery decisions tracked in DECISIONS, each with a deadline.
  • P01-T02 validation (exact, from backend/): go test ./... exit 0 (no test files yet); go build ./cmd/... exit 0 (api/worker/migrate compile); go vet ./... exit 0; gofmt -l . clean; toolchain auto-switched to go1.27.1 (bare go 1.27 directive did not resolve via proxy — pinned toolchain go1.27.1 fixes it); all three binaries boot, print their not-wired notice and exit 0; no Android/Kotlin reference in *.go.
  • P01-T03 validation (exact, from backend/): go test ./internal/platform/config/... 9 tests PASS; go test ./..., go build ./cmd/..., go vet ./... exit 0; gofmt -l . clean. Negative runs: staging/prod without DSN, unknown env, malformed DSN and invalid limits all exit 1 naming only the variable; secret DSN never echoed; LogValue omits DSN. backend/.env stays ignored, backend/.env.example trackable via narrow exception.
  • P01-T04 validation (exact, from backend/): go test ./internal/platform/telemetry/... 6 tests PASS (role/code/request allowlist, UTC timestamps, B-BR-011 fixtures absent); go test ./..., go vet ./... exit 0; gofmt -l . clean.
  • P01-T05 validation (exact, from backend/): go test ./internal/platform/httpserver/... 7 tests PASS (request-ID passthrough/generation, 413 body cap with wide-cap control, 100ms slow-header timeout, graceful drain of in-flight request, access log without sensitive data using route templates, 404/405 logged as unmatched with request ID, bad-options matrix); go test ./..., go build ./cmd/..., go vet ./... exit 0; gofmt -l . clean. Dependency review: chi v5.3.2 (mandated by ADR-005, stdlib mux rejected to honor it), MIT license verified in module cache, zero transitive deps via go mod graph. Live smoke: wired api binary serves 404 with X-Request-Id + access record and drains on SIGTERM. Transport cap is config MaxBodyBytes; per-endpoint 64 KiB JSON enforcement lands with handlers (API_PLAN).
  • P01-T06 validation (exact, from backend/): go test ./internal/platform/health/... 5 tests PASS (live ignores failing checks and never invokes them; ready 503 fails closed with secret-bearing check errors absent from body and logs; per-check timeout; minimal single-key envelope; no-store); go test ./..., go build ./cmd/..., go vet ./... exit 0; gofmt -l . clean. Wired GET /health/live|ready in cmd/api with zero checks — DB/schema probe lands with the pool in P01-T09. Live smoke: both 200, ready carries no-store + request ID.
  • P01-T07 validation (exact): docker compose -f infra/compose.dev.yml config exit 0 with host_ip: 127.0.0.1; up -d db → anpfuel-dev-db-1 health healthy, ports 127.0.0.1:5434->5432 only; psql proves PostgreSQL 18.6 + PostGIS 3.6 + working ST_DWithin; fresh named volume anpfuel-pgdata-dev, no production data. Image pinned postgis/postgis:18-3.6@sha256:60f6ad1d…. Host 5432/5433 taken by unrelated projects → 5434, so dev DSN moved to :5434 in backend/.env.example and config default. Backend go test ./... still exit 0.
  • P01-T08 validation (exact, from backend/): go test -tags=integration ./internal/platform/migrate/... 4 tests PASS against real PostGIS (empty→apply→PostGIS_version ok; second apply no-op; checksum-mutation and stray-file failures; concurrent runners apply once via advisory lock; isolated DBs per test, no residue); go test ./..., go build ./cmd/..., go vet (+integration) exit 0; gofmt clean. Dependency review: explicit stdlib+pgx runner chosen over migrate/goose (ADR-005 already mandates pgx; zero new framework); pgx v5.11.0 MIT, runtime transitives permissive (pgpassfile/pgservicefile/puddle/x-text/x-sync). Real binary: first run applied [000001], second already current. Test-pollution incident caught by the suite: pgx ConnConfig.ConnString() ignores reassigned Database (helper now swaps dbname at URL level); stray ledger row in dev anpfuel removed.
  • P01-T09 validation (exact, from backend/): go test -tags=integration ./internal/platform/database/... 7 tests PASS (options matrix, malformed DSN, blackhole connect-timeout 300ms enforced, cancelled ctx, closed-pool fails loudly, sqlc PostGISVersion smoke vs real DB); go test ./..., go build ./cmd/..., go vet (+integration) exit 0; gofmt clean; sqlc vet + sqlc generate exit 0 and re-generate is idempotent. Tooling review: sqlc v1.31.1 (MIT, installed via go install, pinned in README); pgx transitives permissive only. Caught by tests: pgxpool panics on zero HealthCheckPeriod → validation now requires it positive. Wired lazy pool + db readiness check in cmd/api (P01-T06 note fulfilled): live 200/ready 503 with DB down and process alive, ready 200 with DB up, no secrets in logs.
  • P01-T10 validation (exact, from repo root): docker build -f infra/docker/Dockerfile --target api . exit 0 (same for worker/migrate); api container boots, /health/live 200, docker stop exits 0; migrate image runs against dev DB via injected DSN (already current, exit 0); worker boots exit 0. Image review: user 65532:65532, Env without secrets, history without credential layers, revision label from git HEAD. Pins: golang:1.27.1-bookworm@sha256:69a7b978…, distroless/static-debian12:nonroot@sha256:afa5c872…. Sizes 9–20 MB.
  • P01-T11 validation (exact): vacuum lint -r contracts/openapi/vacuum-rules.yaml contracts/openapi/v1.yaml 52 rules, 0 errors, 0 warnings, 100/100 (from repo root); go test ./internal/platform/apicontract/... 22 vectors + vocabulary bridge + local-refs PASS; go test ./..., go vet, gofmt clean. kin-openapi v0.149.0 (MIT, test-side example validation), vacuum v0.30.6 (MIT, pinned in contracts/README). Caught: invalid http signature securityScheme stub (replaced by prose auth reference for P03-T01); vacuum extends: recommended silently loads 0 rules (config uses spectral:oas + boolean waivers, verified 52 active); missing examples/tags/combinator fixed in-spec. Wire vocabulary frozen from DOMAIN_MODEL/API_PLAN with A05 bridge guard (PREMIUM rejected).
  • P01-T12 validation (exact): bash scripts/check-backend-fast.sh exit 0 (gofmt/build/vet/unit/staticcheck/sqlc-vet+diff/vacuum-100/secret scans); govulncheck ./... clean after bumping x/text v0.29.0→v0.39.0 for GO-2026-5970 (x/sync→v0.21.0); go test -race -count=1 -tags=integration ./... exit 0 locally. Gate failure proof (each reverted): unformatted file, corrupted vector, fake ghp_ token — all exit 1 with cause. Tooling review: staticcheck v0.8.1 MIT, govulncheck v1.8.0, vacuum v0.30.6 MIT (binaries need Go ≥1.27 build or typecheck breaks). CI: new path-aware backend.yml (fast + PostGIS service jobs, no secrets, integration never skips); ci.yml keeps ./gradlew test with docs-only paths-ignore.
  • CI evidence: first backend run 36460303470 failed both jobs and caught two real wiring bugs — (1) committed grep-pattern literals tripped the tracked secret scan (both scanner scripts allowlisted with rationale), (2) runner steps cannot resolve the postgres service hostname (URL now localhost:mapped-port). Fix commit 3540011; re-run 36461273272 success on fast+integration; Android CI 36461273167 success (./gradlew test, prior commit run 4m14s also success).
  • G01 evidence: prerequisite report (TOOLCHAIN/BASELINE_VALIDATION); build/unit/static/vuln gates green; typed config; HTTP lifecycle + live/ready; loopback PostGIS 18.6/3.6; migrations from empty with ledger; pinned images boot/terminate; base OpenAPI lints 100/100 with 22 vectors; Android baseline BUILD SUCCESSFUL recorded (blockers resolved before G09).
  • Next microtask: P02-T01 — Shared ANP fixtures.
  • Backend release G09: NOT STARTED. Android integration P10: BLOCKED BY G09. Paid services P11: LATER.
  • Completed artifacts: upstream snapshot; current-state audit; product/architecture/domain/API/data/ANP/security/testing/infra/migration/business plans; 73 roadmap microtasks; 9 new ADRs; agent contract; risk/decision/requirements registers.
  • No commit, push, release, production migration or infrastructure provisioning performed.

After a task: replace current phase/task/status, record exact commands/results/limitations and next task. Link longer evidence instead of appending full session transcripts. Never mark a phase complete solely because its documentation exists.