Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming. Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
5.1 KiB
Bounded City read snapshots and literal Path boundaries
Implemented 2026-09-14. This is a bounded repair of CITY-04/CITY-06, not completion of the City review or its lazy projection plan.
Read contract
GetCityMapContext uses one read-only SQLite transaction with a two-second
deadline, shortened by request cancellation. The topology version, Quartiers,
Streets, Spots, Page placements and relations all come from that same snapshot.
Each cursor is fully scanned, checked and closed before the next query; a
one-connection pool therefore works without nested-connection deadlock.
Quartiers, Streets, Spots and relations use four bulk cursors. Page placements still use one bounded query per Spot, on the same transaction/connection. Parent joins require current-Domain active Quartiers/Streets/Spots. Foreign or archived parents cannot introduce children into the model. Explicit Page edges require a current-Domain Path binding, including edges left behind after moving the last binding to another Domain. Relations require two visible active Spots.
The projection fails with ErrCityMapBudget rather than silently truncating:
| Budget | Limit per complete map |
|---|---|
| Quartier + Street + Spot nodes | 4,096 |
| Page placements, including multiple semantic appearances | 20,000 |
| Relations examined | 8,192 |
| Database snapshot / connection wait | 2 seconds |
Errors return an empty model, not partial topology with apparently successful counts. Spot counts deduplicate Page UUIDs while preserving distinct typed edges. Exact boundary Pages remain preferred portals. Query/scan/version errors are propagated, and all error/cancellation paths release cursors and connections.
ListSpotPagesContext applies the same two-second read transaction and 20,000
placement safety limit to an HTTP Spot projection. Trusted ListSpotPages
retains its complete-set contract. This is a safety ceiling, not pagination.
No Page bodies or revision histories are read for these projections.
HTTP map/detail/Page projections return 503 with Retry-After: 5 when a
safety ceiling or request deadline is reached, rather than misreporting a
large locality as missing. Missing or unreadable localities remain 404;
unexpected storage failures remain 500.
The server's separate request-scoped read-policy filter remains mandatory: a consistent Domain snapshot is not authorization to see every locality or Page. No cross-principal model cache or topology-only public ETag is introduced.
Literal boundary contract
All SQL containment/overlap matching in city.go and city_operations.go uses
case-sensitive binary segment ranges, not LIKE. A normalized non-root boundary
/a%_ contains its exact Path and the range [/a%_/, /a%_0); %, _, backslash
and Unicode are ordinary characters. /A does not contain /a, and /life
does not contain /life2. An empty legacy boundary contains nothing.
Root / covers every absolute Path. Creating it therefore conflicts with any
other active Quartier boundary, regardless of creation order. Streets and Spots
still require strict descendant Paths and their existing valid parent/Domain.
No raw Path or UUID is changed, decoded again, lowercased or escaped in storage.
Creation validation, import overlap lookup, Path-context resolution, inferred
Page membership, appearance lookup and health checks use these semantics.
Context and health use bounded read snapshots too. The /u health exclusion
includes the namespace root and descendants, not unrelated or differently-cased
Paths. Health is still a basic topology summary, not a full reconciliation of
manual membership overrides and all curation semantics.
Verification and remaining work
city_read_test.go covers a one-connection pool, WAL concurrent commits between
snapshot pinning and topology loading, all three size ceilings, connection-wait
cancellation, nested scan errors, connection release, foreign/archived parent
edges, foreign explicit Pages, literal wildcard/case/Unicode boundaries, root
overlap, and health/context/overlap consistency. Existing City/import/organizer
tests remain regression gates.
2026-09-14 named references: /v/city/s/{quartier}/{street} resolves in one
bounded query with its current active parent. Legacy unique Street names and
explicit uuid: references still work; ambiguous legacy references fail closed
with the same 404 as missing/hidden nodes. Details check ancestor read access,
do not load the map, and propagate cancellation. Breadcrumb macros defer map
loading until nearby actually needs it. Literal Page links encode ?/#/%.
Regressions: city_reference_test.go, city_links_test.go, and Chromium
city-links.js (normal, popup and all three initial-focus levels).
Still pending: lazy paginated locality/Page APIs; removal of per-Spot Page queries; size limits for individual legacy metadata fields; context propagation to remaining health/macro callers; full URL-autoplan provenance/atomic adoption. Large City data can currently exceed a safety ceiling and show an error until lazy projections are implemented. Raising global limits is not a replacement for that work.