Task: Bring ores.geo to the clean standard

ores.geo passes the Component Clean Standard for a component of kind All.

ores.geo is a hand-written, model-less C++ library, so the model, protocol, wiring and shell sections do not apply. The audit found stale documentation, hygiene defects and a test suite that could not fail, and the rewritten test found a real defect in the component's SQL. The item table records that outcome item by item. V06 records the programme gap.

• Every checklist item that applies to a component of kind All passes, or is recorded with the reason it does not apply.
• Every item that cannot pass is recorded as an exception with its reason.
• Every generator defect found is fixed at its source, with a regression test.
• No consumer is left broken. The whole tree builds with the component.

The original acceptance asked that ores.geo join COMPONENTS_UNDER_TEST. That cannot be met and is superseded, because ores.geo is not a codegen component. V06 records the reason.

The survey below was recorded on 2026-09-25 by an agent that did not write the component. Every finding was re-verified on this branch before the work, and one defect the survey missed was found by the rewritten test.

Survey, 2026-09-25, at trunk 5de59e3fb8, by an agent that did not write the component. Every claim was re-verified on this branch.

• Keep the component. The retirement hypothesis fails: ores.http builds the service at application.cpp:86 and calls lookup at iam_routes.cpp:502 inside the login handler, and the result becomes session.country_code. That is the only production call site.
• The use is inert, for two independent reasons.
  1. The geo table is empty after a recreate. compass db recreate loads the ip2country TSV into the dq staging table only. The dq publish function ores_dq_ip2country_publish_fn is the only writer of ores_geo_ip2country_tbl, and no recreate step runs it. Measured after the recreate: geo_rows=0, artefact_rows=512186. The standalone ip2country_import.sql cannot fill it either, because its insert omits the NOT NULL tenant_id, and no aggregator runs it.
  2. The IP conversion was wrong. This the survey missed, and the rewritten test found it. ores_geo_inet_to_bigint_fn computed the address from get_byte(inet_send(ip), 0..3), which on this PostgreSQL are the family, bits, is_cidr and address-length bytes. It therefore returned 35651588 for every IPv4 address, so even a populated table could not answer. The fix uses ip_address - '0.0.0.0'::inet, which returns the address as an integer for any IPv4 address.
• Scale. 5 production C++ files in 4 headers and 1 source, with 2 files under tests/. Originally 5 test cases and 5 assertions that could not fail; now 4 cases and 8 assertions that can.
• The data path is recorded, not wired. Wiring the publish into the recreate flow is a data-pipeline change, not a component clean-up: the natural insertion point ip2country_populate.sql is generator-owned and already drifted, the publish is a SECURITY DEFINER truncate-and-reload of about 512k rows, and a backlog capture already exists for moving ip2country onto the org dataset pipeline. The overview and the service header now state that a fresh database answers address_not_found until a publish has run.
• The diagram runs the two passes. The capture gives the class boxes, and the hand pass adds the members and relationships they do not carry, such as the constructor, the two lookup signatures and the service-to-result and service-to-error arrows. PlantUML resolves a relationship only in the namespace block that declares its classes, so the hand-authored lines sit above the sentinel, and the warning below the sentinel says a capture run rewrites them.

Work items, and their outcome.

1. Overview rewritten. Done, see M10.
2. Stale ground truth fixed on the Foundation layer page. The ores.utility.hpp header that carried the same claim no longer does: the geo facet it advertised never existed, and its restored text drops it. Done.
3. Unused ores.geo.lib link removed from ores.iam/core. Done, see H02.
4. See also filled with id links to ores.database, ores.http.core, ores.http.server and the Foundation layer page. Done.
5. Tests rewritten so they can fail. Done, see V02. It found the conversion defect.
6. Data path decided: recorded, not wired. See the note above.
7. Hygiene: the unused <optional> include removed, the dead enum value removed, the stale script name corrected. Done.
8. Umbrella headers kept with corrected text, because the component and facet umbrella headers are the documented namespace headers. Done.

Manual QA scenarios (scaffolded via compass add test_scenario) that verify this task. Link new ones here as they're created; the scenario doc itself links back via its "Verifies task" field.

No scenario applies. No user reaches the component directly; the one consumer is the login route, and the change is a doc, hygiene, test and SQL fix. The build, the component suite and the gates are the evidence.

ores.geo is brought to the Component Clean Standard short of the registry entry, which the standard's own exception rule covers.

The component is a hand-written simple library, and it stays. The work is a rewritten overview and the same stale claims removed from the Foundation layer page, the generated marker on its two CMake source lists, a hygiene pass that removed a dead enum value, an unused include and the stale script name, an unused link removed from ores.iam.core, and tests that can fail.

The tests found a defect the survey missed. ores_geo_inet_to_bigint_fn converted an IP address from the inet header bytes, so it returned 35651588 for every IPv4 address and no lookup could ever match a range. It is fixed at source, and the seeded test fails again if it regresses.

Verification. The whole tree builds with compass build, exit 0. The ores.geo suite passes 8 assertions in 4 test cases, the ores.codegen suite 550, and the ores.compass suite 230 with 1 skipped. The database recreates from scratch, which is the SQL fix's own proof. Every codegen gate passes.

The one exception is V06. ores.geo does not join COMPONENTS_UNDER_TEST because it is not a codegen component.

The data path is recorded, not wired. A database built from scratch answers address_not_found until the dq ip2country publish path has run; the overview and the service header now say so.