# Phase 2A Plan Phase 2A is a read-only shadow implementation. It is split into six independently reviewed subphases so that each new boundary is evidenced before the next one is introduced. Every subphase receives its own branch, pull request, handoff, review, merge, and `/clear` before the next subphase begins. No subphase is accepted merely because its code exists; the stated acceptance gate and review evidence are required. ## 2A.1 — Foundation and guardrails ### Scope Create the Python `src/` package, immutable configuration and domain contracts, read-only ports, standard-library CLI, offline tests, and CI. The configuration must reject Noco writes, stale deletion, MCP, and scheduler enablement. Planned actions are report-only. ### Acceptance gate The required local commands pass, CI is green, the CLI doctor is deterministic in JSON mode, and structural tests show that no production writer or mutation client is present. The review handoff confirms no network, database, NocoDB, PBF, deployment, or production-data access. ### Explicitly prohibited capabilities No PostgreSQL/PostGIS connection, NocoDB connection, NocoDB write surface, PBF download or parser, migration, sidecar database, scheduler, worker, FastAPI application, MCP server, deployment, or legacy scraper change. ### Expected review evidence Branch and base SHA, exact test/lint/type/build/CLI output, CI status, module surface inspection, no-network test coverage, changed-file inventory, and shared handoff checksums. ## 2A.2 — Sidecar schema and migrations ### Scope Add the PostgreSQL/PostGIS sidecar schema and versioned migrations for source snapshots, OSM identities, presence evidence, profile decisions, provenance, and reconciliation read models. ### Acceptance gate Migrations apply and roll back against an isolated test database, schema constraints are tested, and no NocoDB schema or production database is modified. ### Explicitly prohibited capabilities No production database connection, direct NocoDB PostgreSQL writes, NocoDB mutation adapter, PBF ingestion, scheduler, deployment, or stale deletion. ### Expected review evidence Migration diff, isolated database test output, schema contract review, rollback evidence, and proof that the sidecar is separate from NocoDB. ## 2A.3 — PBF ingestion foundation ### Scope Add checked-in small PBF fixtures, parser boundaries, source snapshot metadata, and Geofabrik download/checksum validation for approved test inputs. ### Acceptance gate Fixture parsing, object counts, supported object types, and download validation pass without accepting an unverified extract. ### Explicitly prohibited capabilities No production PBF download, unbounded ingestion, NocoDB access, profile classification, reconciliation writes, scheduler, or deployment. ### Expected review evidence Fixture provenance, parser tests, checksum/size validation output, bounded resource behavior, and network behavior limited to an explicitly approved test path. ## 2A.4 — Profiles, normalization, and deduplication ### Scope Implement versioned profile rules, deterministic category/field normalization, and duplicate candidate generation over parsed source objects. ### Acceptance gate Golden tests demonstrate profile-version behavior, normalization stability, and deterministic collision/candidate output. ### Explicitly prohibited capabilities No NocoDB writes, stale deletion, production reconciliation, unreviewed profile changes, scheduler, or deployment. ### Expected review evidence Profile fixtures, versioned rule evidence, normalization vectors, collision reports, and deterministic rerun results. ## 2A.5 — Noco read adapter and adoption scanner ### Scope Implement the read-only Noco adapter and scan existing rows for adoption, duplicate, ownership, and workflow-protection evidence. ### Acceptance gate Reads are schema-fingerprinted, bounded, auditable, and tested against safe fixtures or an explicitly isolated read-only environment. No mutation method is exposed. ### Explicitly prohibited capabilities No NocoDB create/update/delete, direct PostgreSQL writes to Noco, production reconciliation, stale deletion, scheduler, or deployment. ### Expected review evidence Read request logs without secrets, schema fingerprint, fixture/isolated read results, duplicate analysis, protection evidence, and method-surface review. ### Implementation under review Draft PR #7 implements a two-method read port (`read_schema`, `iter_pages`), an immutable fixture adapter, and a PostgreSQL adapter that accepts only an injected fetch-only executor. Schema drift fails closed before row scanning; keyset pages, source inputs, mapping evidence, candidate fanout, and final reports are explicitly bounded. The scanner emits deterministic non-executable evidence for exact, high-confidence, ambiguous, unmatched, and collision outcomes. It records workflow-protection reasons and active-mapping conflicts but does not persist a candidate, create an active mapping, or expose a Noco mutation method. Adversarial tests reject dishonest page ordering or continuation, oversized iterables, duplicate report evidence, and report-hash omissions. No live Noco scan or production connection is part of this subphase. ## 2A.6 — Integrated shadow reconciliation ### Scope Combine source snapshots, profile decisions, and Noco read evidence into immutable shadow reconciliation reports with deterministic planned actions. ### Acceptance gate End-to-end shadow runs are repeatable, action keys are stable, protected or ambiguous records are skipped, and reports contain sufficient evidence for review. ### Explicitly prohibited capabilities No production writes, stale deletion, autonomous scheduling, deployment, MCP, or changes to the legacy scraper. ### Expected review evidence End-to-end fixture report, rerun comparison, action/evidence audit, protected row cases, ambiguity cases, and explicit production-impact confirmation.