# Project State ## Repository state Release `0.4.0` is merged and deployed. It replaces the ACT-only runtime boundary with a read-only OpenStreetMap lead generator for 58 sovereign English-language markets. The release includes: - a validated 58-country market registry; - country calling-code normalization metadata; - live Geofabrik catalog ingestion; - recursive smallest-available source sharding; - bounded country extraction for shared regional PBF files; - generic per-shard profile generation; - aggregate cross-shard deduplication and progress evidence; - running, partial, and completed dashboard states; - a preview-by-default `market-run-once` CLI that reuses the scheduler worker for exactly one foreground cycle without requiring scheduler approval; and - unit coverage for market selection, shard planning, extraction, shard processing, aggregation, deduplication, partial failures, and one-shot safety. No live NocoDB create, update, delete, adoption, or lineage write has occurred. ## Current production deployment - Coolify application: `osm-lead-source-service` - Application UUID: `ny8uluv6fl1a76hgbgfvokjf` - URL: `https://ny8uluv6fl1a76hgbgfvokjf.luxeillum.com` - Repository: `git@github.com:lutzkind/osm-lead-source-service.git` - Branch: `main` - Current release: `0.4.0` - Current deployed source commit: `03a1ea1c1e5f85cab0468a30b119567b180bb7f9` - Current scope: 58-country read-only worker - Service status: `running:healthy` - Runtime mode: `shadow-read-only` - Scheduler request: present - Scheduler approval: absent - Effective scheduler state: disabled - Startup execution: disabled by default - Writer enabled: no - Noco writes enabled: no - Stale deletion enabled: no - Legacy writer formally disabled: no - Production sidecar configured: no Release `0.4.0` is live but intentionally inert. Scheduled execution cannot start until the independent scheduler-approval gate is explicitly enabled. The foreground `market-run-once` path is deployed, but executed runs remain blocked until durable storage is attached and persistence is verified. ## Release 0.4.0 market scope The default `OSM_LEAD_SOURCE_COUNTRIES=all` selection contains 58 sovereign states where English is official or the de facto national language. Large countries are split through the Geofabrik catalog into the smallest available non-overseas child extracts. Countries without their own Geofabrik extract use an explicitly approved shared source plus a fixed country bounding box and `osmium extract --strategy=complete_ways`. The worker processes shards sequentially, writes a bounded progress snapshot after every shard, continues after isolated failures, and deduplicates country-scoped OSM identities across overlapping source shards. ## Runtime evidence model The dashboard snapshot records: - configured, completed, and failed market counts; - configured, completed, and failed shard counts; - active, review, excluded, and out-of-scope totals; - aggregate category counts; - aggregate source and report hashes; - running, partial, or completed state; and - pending Noco comparison state. Per-shard reports and acquisition evidence are written under the configured report directory. The current deployment uses container-local `/tmp`, so durable storage is required before the first full 58-country production cycle. ## Historical ACT verification ACT was the bounded validation region, not the final product scope. It proved: - checksum-verified Geofabrik acquisition; - bounded PBF parsing; - profile evaluation and normalization; - deterministic reports; and - exact read-only Noco identity comparison. The accepted ACT result contained 980 active identities, with 502 exact existing Noco OSM identity matches and 478 identities lacking the same exact OSM key. No lead was written. ## Noco and writer state The repository contains guarded read-only comparison and controlled insert components, but the automatic market worker has no Noco mutation path. Current fixed boundaries: - Noco creates, updates, and deletes are disabled. - Direct writes to Noco PostgreSQL are forbidden. - The controlled writer cannot arm while the legacy writer remains unverified. - Update execution is unavailable. - Stale-delete execution is unavailable. - No generated candidate may be blindly inserted merely because its exact OSM identity is absent. ## Legacy cutover evidence The legacy `osm-country-scraper` remains online and must not yet be treated as a cleanly completed or retired writer. The long-running United States job `8ef437c9-c6ed-47ff-9bae-f1dcea1e816b` is currently idle at the worker level, but its final NocoDB synchronization is inconsistent: - total synced rows for the job: `4,303,460`; - rows carrying `job_status=completed`: `100`; - rows still carrying `job_status=running`: `4,303,360`; - rows carrying `job_status=partial` or `job_status=failed`: `0`. The completed rows were written on `2026-07-15 18:12:46 UTC`, and the legacy runtime logged a NocoDB synchronization timeout. This is evidence of a bounded final-status propagation failure, not evidence that only 100 leads completed. The legacy SQLite job state and final artifacts must be captured and reconciled before formal writer cutover or retirement. ## Remaining production gates Release `0.4.0` validation, merge, deployment, health verification, and fail-closed scheduler deployment are complete. The actual remaining gates are: 1. Attach durable cache/report/dashboard storage and verify persistence across a restart and redeploy. 2. Use the validated `market-run-once` command for a controlled read-only subset covering both direct country extracts and a shared-source country crop; accept its reports and resource use. 3. Run the complete 58-country read-only cycle and retain source, shard, report, and aggregate hashes. 4. Run generic read-only Noco identity, adoption, duplicate, ownership, and workflow-protection comparison against the generated reports. 5. Provision and migrate the isolated PostgreSQL/PostGIS sidecar; prove backup, restore, rollback, and isolation from NocoDB. 6. Review duplicate, provenance, adoption, lifecycle, and capacity evidence. 7. Capture the legacy United States job's authoritative SQLite state and final artifacts, reconcile the partial NocoDB status propagation, and record formal legacy-writer cutover evidence. 8. Approve and execute a deliberately small capped insert-only pilot through the guarded NocoDB API writer. 9. Add monthly source-presence, missing-counter, and quarantine evidence only after the insert pilot is accepted. 10. Keep updates and stale deletion disabled until separately implemented and approved under the two-snapshot/60-day policy. The canonical completion handoff is `docs/handoffs/2026-07-21-repository-completion.md`. ## Non-goals for the current release - No Noco import is enabled by `0.4.0`. - No update or delete lifecycle is enabled. - No stale business deletion is enabled. - The scheduler request is inert without a separate explicit approval flag. - No new MCP tools or profiles are added. - No Windmill dependency is introduced.