Stability checkpoint — README mastery + DB defaults align + ryuk-disable (testcontainers network path now the next blocker)
- docs(readme): add 'What this project demonstrates mastery of' 10-axis block at top
(README.md +16 LOC) — sourced from stable-py-v0.6.9 tag annotation
themes ; sits ABOVE the badges per the new
~/.claude/CLAUDE.md "Surface the same themes at the TOP of the
README" rule (formalised cross-repo in mirador-common ADR-0062).
- fix(config): align Python DB defaults with the local-dev
postgres-demo container
(src/mirador_service/config/settings.py +11 / -4 LOC) — defaults
go from `mirador/mirador/mirador` to `demo/demo/customer-service`
matching Java's application.yml + the postgres-demo Docker
container env. `uv run mirador-service` now boots without manual
MIRADOR_DB__* env-var setup. CI unaffected (test.yml sets
MIRADOR_DB__USER=mirador explicitly via GitLab `services:
postgres:` block) ; prod unaffected (overrides via standard env
vars).
- fix(ci): disable testcontainers ryuk to unblock integration-tests
(.gitlab-ci/test.yml +14 LOC) — adds
`TESTCONTAINERS_RYUK_DISABLED: "true"` to the integration-tests
variables block. This fixes the ryuk session-creation 409
conflict that blocked 23 consecutive runs ; tests now actually
RUN, but reveal a deeper issue (see Known limitations).
CI :
- ✅ Main pipeline #194 — https://gitlab.com/mirador1/mirador-service-python/-/pipelines/2481877956
- Required jobs all green : ✅ unit-tests | ✅ pip-audit |
✅ import-linter | ✅ mypy --strict | ✅ ruff:lint |
✅ docker-build | ✅ benchmarks | ✅ pages
- 🔴 integration-tests : failed (allow_failure=true ; new failure
mode — see Known limitations). Different from stable-py-v0.6.9's
ryuk 409 ; that one is FIXED, the next blocker surfaced.
- ⏭ compat-py312 / compat-py313 / sonarcloud : manual or skip-on-no-token
- ✅ MR pipelines for !32 (README), !33 (DB defaults), !34 (ryuk) all
green individually before auto-merge fired.
Local test pass :
- ⏭ uv run pytest — N/A in this annotation window (CI ran the full
unit suite on the merged HEAD).
- ⏭ ruff / mypy — N/A (CI green).
- ✅ Manual : `MIRADOR_SERVER_PORT=8001 uv run mirador-service` boots
without DB env-var overrides — defaults align worked. Verified
9:54 local, claude mcp list shows mirador-python ✓ Connected.
Manual probe :
- ✅ Smoke test via claude --print : `claude --print "Use mirador-python
MCP's list_recent_orders limit=3"` → returns 3 (matches Java sibling
output, polyrepo interchangeable contract validated).
- ✅ X-API-Key middleware shipped in stable-py-v0.6.9 still works :
http POST /mcp/ with `X-API-Key: demo-api-key-2026` returns the
full server capabilities block (protocolVersion 2025-06-18, 14
tools listChanged).
Regression check vs previous tag (stable-py-v0.6.9) :
- ✅ X-API-Key auth path unchanged — both JWT and API-key still land
on identical AccessToken shape.
- ✅ MCP tool catalogue unchanged at 14.
- 🆕 ryuk 409 conflict resolved — tests no longer fail at session
creation, they at least RUN the test logic now.
- 🆕 New failure mode surfaced : 6 postgres tests + 6 kafka tests
fail with `ConnectionRefusedError` on 172.17.0.1:<random_port>.
Root cause : testcontainers spawns containers via the host
Docker socket, but the runner container's network can't reach
the host-published random port via the Docker bridge gateway.
Carried forward as a NEW known limitation (see below).
- ⏭ N/A — no MCP / Spring AI change in this rev. The 14 in-process
tools shipped in stable-py-v0.6.9 still work end-to-end.
- ⏭ N/A — no auth surface change. X-API-Key middleware (parity
with Java) shipped in stable-py-v0.6.9 still functional.
- ⏭ N/A — no domain change. Customer / Order / Product / OrderLine
surface and 6 invariants (shared ADR-0059) untouched.
- ⏭ N/A — no deploy / IaC / cluster change.
- ⏭ N/A — no SLO / dashboard / alert / runbook change.
- 🆕 **DB defaults aligned with the local container** — DX win :
`uv run mirador-service` boots out-of-the-box on a dev machine
with the standard postgres-demo container. Removes a recurring
point of confusion documented as a TASKS.md item.
- 🆕 **Testcontainers ryuk reaper disabled** — unblocks the test
session creation step that blocked 23 consecutive runs. Tests
now actually start and exercise their logic ; deeper network
path issues exposed (carried as new known limitation).
- All required jobs green on main #194.
- Integration-tests still allow_failure=true ; remains shielded
pending the network-path fix (not a regression — pre-existing
shield, just blocked by a new root cause).
- 🆕 **DB defaults documented** match the polyrepo interchangeable
contract — Java + Python both default to demo/demo/customer-service
for local dev, both override identically in prod.
- ⏭ N/A — backend repo.
- 🆕 Single-key onboarding : `export MIRADOR_API_KEY=demo-api-key-2026`
+ `export GRAFANA_TOKEN=glsa_…` (saved to ~/.zshenv this session)
+ run `bin/dev/mcp-setup-infra.sh` + `bin/dev/mcp-setup-app.sh` →
11/11 MCPs ✓ Connected (filesystem, postgres, kubernetes, docker,
redis, prometheus, grafana, home-assistant, elgato + mirador-java
+ mirador-python).
- 🆕 ADR-0062 (mirador-common) formalises the thematic 10-axis
pattern AND verbose tag annotations cross-repo.
- mutmut blocked — boxed/mutmut macOS issue (unchanged).
- Docker image alpine — pydantic_core / cryptography / bcrypt no
musl wheels (unchanged).
- 🆕 **integration-tests network path** : after disabling ryuk, the
6 postgres + 6 kafka testcontainers tests now fail with
`ConnectionRefusedError ('172.17.0.1', <random_port>)`. The
testcontainers-spawned Postgres / Kafka container publishes a
random port on the macbook-local runner host ; the runner
container itself can't reach those host-published ports via the
Docker bridge gateway. Three possible fixes (none trivial) :
1. Wire GitLab `services: kafka:` for kafka tests + use the
existing `services: postgres:` for postgres tests, drop
testcontainers in favour of GitLab service aliases.
2. Run integration-tests via dind (privileged=true) so the
network namespace matches.
3. Mount the runner with `--network host` so 172.17.0.1 resolves
to the localhost socket.
Pre-existing in spirit (the 23 prior red runs were hitting ryuk
before reaching the test logic) ; SHIPPED into visibility now
that ryuk is out of the way. Tracked as TASKS.md item ; flip to
`allow_failure: false` still blocked.
- sonarcloud rule-skipped — SONAR_TOKEN not configured at the
group level (unchanged ; user action required).
- mirador-python on port 8001 (override) when running parallel to
Java on 8080 — per the shared port contract, this is the
documented workaround. Single-backend dev runs don't need the
override.
- Pick a fix for the testcontainers network path issue (option 1
is the cleanest — declare GitLab `services:` for postgres + kafka).
- Update the README full-body sync (FR is at 342 lines vs EN's
1118 — partial mirror just landed via java !231 for the mastery
block only ; the corpus needs its own translation session).
- Wire the README mastery block update into release-please /
changelog tooling so it auto-syncs from tag annotations rather
than drifting.