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

92 lines
5.1 KiB
Markdown

# 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](city-review-and-reconciliation.md) 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.