Regional page names can be readable while their encoded routes and generated files disagree. Inspecting the actual page generator led me to separate route construction and output reconciliation into a small independent module.
A route and a filesystem path have different representations
The source generator creates combinations of regions and facility types. A browser route is encoded while an output folder may retain readable Unicode. Comparing the raw strings directly can misidentify an existing file as missing or conflate distinct routes. The new example starts both from the same declared segments.
Synthetic region and space segments produce a relative encoded route and a readable index file path. No business origin or actual regional directory is imported. This checks a path contract; an HTTP check that a deployed server serves the document remains separate.
Normalize visually identical text before encoding
Equivalent Unicode sequences are normalized to NFC before per-segment encoding. Duplicate normalized routes fail. Detecting them after building a dictionary would be too late if one entry had already replaced another.
Segments reject slash, backslash, query and percent-control characters, preventing a pre-encoded separator from bypassing the declared structure. This is a narrow document-generation contract rather than a universal URL parser. Names enter as plain segments, not arbitrary addresses.
Reconcile generated output and discovery separately
The manifest declares route, file, audience and sitemap membership. Reconciliation compares expected files with a supplied output inventory and expected discovery paths with a supplied sitemap. Missing and unexpected entries are separate results; existence in one list cannot prove correctness in the other.
Recorded examples include an exact match and missing output. Duplicate output entries also fail. The function neither scans a real build directory nor writes files to another site. A caller must connect a genuinely observed output inventory to this contract.
Maintain one document identity across representations
Normalization and encoding do not erase readable names. They create a transport representation alongside a display representation for one document. Display names can remain original while route comparisons use one normalized basis, reducing the possibility of visually identical entries overwriting each other during a build.
The module writes no file, so a file field is not evidence of generation. A real generator’s observed inventory must be reconciled afterward. Distinguishing a changed route, changed file location and changed discovery entry also makes a correction’s impact explainable.
A broader integration may add host, extension and redirect policy as configuration. This contract deliberately handles relative routes and index files only. It expands from demonstrated boundaries rather than promising untested platform behavior.
Do not equate a path contract with deployment verification
Eight tests passed in source and fresh ZIP extraction, covering Unicode encoding, normalization collisions, unsafe segments, audience distinctions and inventory mismatches. They do not verify DNS, search-engine indexing or deployed authentication. A policy declaration and its operational enforcement remain separate.
When generating more regional pages, the useful question extends beyond count: can each document be traced to its route, output file and discovery entry? I share a reproducible reconciliation structure rather than relying solely on a successful generation message.
A generator integration must obtain an actual output inventory after building. Passing the expected list back as if it were observed would make the comparison circular. The manifest defines expectations; independent observation supplies the evidence against which they are checked.