Files
pages/docs/design/city-read-integrity.md
T
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
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.
2026-09-27 14:44:43 +09:00

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.