# Knowledge City Model Detailed Design Implementation review (2026-09-13): see [City review and URL-driven reconciliation](city-review-and-reconciliation.md) for verified gaps and the repair checklist. Authorization, geometry and cache requirements here are design targets, not claims that every current code path already satisfies them. Label follow-up (2026-09-13): the current map shows its active level's labels without hover. Street names are horizontal text anchored to their roads (no textPath rotation), including in the Street detail view. Hover/focus retains road highlighting; the explicit Labels toggle hides/shows the current renderer's labels. Normal and popup views have Chromium regressions using vertical/diagonal road fixtures. This does not implement the broader event/Worker/UI repair plan. ## Purpose The [manual organization UI](city-organization-ui.md) supports display-title edits, multi-selection, Spot merging and Street relocation. These preserve document URLs and use explicit Page memberships when the new boundary differs. Spot nesting remains invalid; use a Street parent or merge into another Spot. Knowledge City is a human navigation and governance model over the existing Domain, Page UUID, Revision, Document, and semantic-path planes. It must make a large body of knowledge understandable, maintainable, and traversable without turning the database back into a filesystem. ```text Campus administrative federation and defaults Domain host-selected namespace and policy boundary Quartier planned knowledge district and policy boundary Street operational sequence of nearby Spots Spot smallest semantic locality and Page graph root Page reusable knowledge object Revision immutable historical representation ``` The city hierarchy answers “where is this knowledge curated?” The SpotGraph answers “what else is semantically connected?” Semantic paths answer “how can this Page currently be reached?” These are separate questions. ## Design principles 1. **Locality is not identity.** Zone, Spot, Page, and Revision have distinct UUIDs. Moving a Page or Spot never changes Page identity or history. 2. **Tree for orientation, graph for knowledge.** Quartier and Street form the ZoneTree. Street points to Spots. Spots form a graph and point to Pages. 3. **One planned placement, many semantic appearances.** A Spot has one primary Street placement. A Page may belong to many Spots and is a MagicPage when it does. Shortcuts do not create a second primary placement. 4. **Path is a projection with a City boundary.** City placement does not replace UUID identity, but each Quartier, Street, and Spot binds one semantic Path prefix used as its primary jurisdiction. Path moves change inferred locality without changing Page identity or history. 5. **Governance follows locality.** Capability defaults may flow Domain → Quartier → Street → Spot. Exceptional Page grants remain explicit. Publication ceilings are restrictive intersections, not overridable defaults: subordinate owners cannot widen superior limits. See [owners and publication](locality-publication-ownership.md). 6. **No destructive topology cascade.** Archiving a Zone or Spot does not delete Pages, Revisions, Documents, path bindings, or external links. 7. **Planning changes are auditable.** Structural operations are transactional, versioned, previewable, and reversible where identity permits. 8. **Language-neutral structure.** Machine names and UUIDs are language-neutral; titles, descriptions, signage, and landing copy may be localized. ## Quartier A Quartier is a deliberately planned aggregation of Streets. It is the largest knowledge-locality boundary below a Domain and exists to make policy and navigation comprehensible at scale. ### Required functions - stable UUID, language-neutral machine name, localized title/description; - charter: purpose, intended audience, inclusion/exclusion criteria; - boundary: owned child Streets; Quartier nesting is not allowed initially; - zoning policy defaults: visibility, curation workflow, retention, templates, language fallback, navigation and search defaults; - governance: curator groups, approval roles, escalation owner and contacts; - explicit Quartier/Spot owner appointments and scoped publication administration, bounded by superior ceilings; ownership does not grant document editing; - entrances: landing projection, featured Spots, announcements and guides; - signage: aliases, keywords, icon/color, breadcrumb label and external links; - scoped search, recent changes, activity feed and subscription; - map and health dashboard for Streets, Spots, orphan Pages and broken links; - lifecycle: draft, active, deprecated, archived; - planning operations: reorder, move Street, merge Quartiers, split Quartier, preview plan, apply transaction, record topology revision; - export/import of topology metadata without copying Page Documents by default. Quartier is not created merely because a Street has many children. Promotion is an explicit planning decision with a charter and redistribution plan. ## Street A Street is the smallest ordered Zone and groups nearby Spots for day-to-day navigation. It represents an understandable route through related localities, not a permissionless directory. ### Required functions - stable UUID, machine name and localized signage; - exactly one parent Quartier in the first implementation; - ordered Spot placements with optional sections and featured entrances; - Street-level policy overrides and curator assignment; - Street landing, compact/detail/map views and scoped search; - activity, vacant/overgrown indicators and maintenance queue; - move, reorder, merge, split and deprecate operations; - a documented route intent such as lifecycle, architecture layer, product area, department workflow, or learning sequence. An unconsolidated Street may temporarily contain loose Page placements. These are not silently treated as Spots. The UI exposes them as an Inbox requiring a curator to create/select a Spot. The Street remains marked `unconsolidated` until the Inbox is empty. ### Street-to-Quartier promotion Promotion preserves the Zone UUID but changes its kind only through a plan: 1. preview affected Spot placements, links, policies and aliases; 2. define at least one child Street and partition all existing Spots; 3. validate names, capabilities and destination conflicts; 4. atomically change kind, create child Streets and move placements; 5. increment topology version and retain an audit/reversal record. A Quartier cannot directly own Spots after the transaction. ## Spot A Spot is the smallest semantic knowledge locality. It is large enough to have its own purpose, curators, Page membership and capability boundary, but it never contains child Spots and cannot be promoted into a Street. An overgrown Spot is split into multiple Spots or has Pages moved/linked elsewhere. ### Required functions - stable UUID, machine name, localized title, summary and curator contacts; - one primary Street placement and lifecycle state; - charter and optional content schema/template; - generated landing projection independent of any one Page; - ordered Page membership with typed edges: `primary`, `guide`, `reference`, `example`, `attachment`, `related`; - Page pinning, featuring, manual ordering and query-backed dynamic sections; - typed Spot-to-Spot relations: `related`, `depends_on`, `supersedes`, `implements`, `learn_before`, `operated_by`; - backlinks, inbound/outbound relation view and shortest knowledge route; - scoped search, activity stream, watchers and change digest; - capability requirements and curator workflow; - health indicators: empty, orphaned, stale, duplicate, overgrown, broken, unreviewed and language-gap; - split, merge, move and archive operations that preserve Pages; - a machine-readable context payload for macros, adapters and future agents. Spot membership is a graph edge, not a path link. Adding a Page to a second Spot creates a MagicPage appearance and does not clone its Revisions. Removing the last Spot edge leaves the Page as an orphan candidate but does not delete it. ## Page placement and MagicPage behavior ### Semantic Path jurisdiction Each active locality binds a normalized, language-neutral Path prefix. A Street prefix must be a strict descendant of its parent Quartier prefix, and a Spot prefix must be a strict descendant of its Street prefix. Boundaries at the same level may not overlap, preventing ambiguous primary locality. For example, `/life`, `/life/home`, and `/life/home/kitchen` may bind Quartier `life`, Street `home`, and Spot `kitchen`. Every Page Path below the Spot prefix is inferred as a primary member of that Spot. Pages below only a Street or Quartier remain in that locality's unconsolidated scope until a Spot boundary is planned. Exact and descendant matching is segment-aware, so `/life2` is not inside `/life`. This inferred primary membership is evaluated from current Path bindings and is not persisted as Page identity. Explicit `spot_pages` edges remain semantic appearances; they can place the same Page in additional Spots as a MagicPage. An explicit edge takes presentation precedence over an inferred edge within the same Spot. Renaming a Page Path may therefore change its inferred primary locality but never its UUID, revisions, or explicit MagicPage appearances. `spot_pages` records why and how a Page appears. The same Page can be primary in one Spot and a reference in another. Each Spot controls its own label, order and visibility of the edge; it does not override Page title/content globally. Viewer responses may expose all other Spot appearances only when the caller can read those Spots. Search and breadcrumbs never leak inaccessible locality names or result counts. Cross-Domain appearances are absolute external references containing the destination FQDN; a local Spot edge never pretends to own a remote Page UUID. ## Topology schema ```sql CREATE TABLE zones ( uuid TEXT PRIMARY KEY, domain_uuid TEXT NOT NULL, kind TEXT NOT NULL, -- quartier, street parent_uuid TEXT, -- NULL for Quartier; Quartier UUID for Street name TEXT NOT NULL, title TEXT NOT NULL DEFAULT '', description TEXT NOT NULL DEFAULT '', charter_json TEXT NOT NULL DEFAULT '{}', policy_json TEXT NOT NULL DEFAULT '{}', state TEXT NOT NULL DEFAULT 'draft', sort_key INTEGER NOT NULL DEFAULT 0, version INTEGER NOT NULL DEFAULT 1, created_at_ms INTEGER NOT NULL, updated_at_ms INTEGER NOT NULL, UNIQUE(domain_uuid, parent_uuid, name) ); CREATE UNIQUE INDEX idx_zones_quartier_name ON zones(domain_uuid, name) WHERE kind = 'quartier'; CREATE TABLE zone_localizations ( zone_uuid TEXT NOT NULL, lang TEXT NOT NULL, title TEXT NOT NULL, description TEXT NOT NULL DEFAULT '', PRIMARY KEY(zone_uuid, lang) ); CREATE TABLE spots ( uuid TEXT PRIMARY KEY, domain_uuid TEXT NOT NULL, name TEXT NOT NULL, title TEXT NOT NULL DEFAULT '', summary TEXT NOT NULL DEFAULT '', charter_json TEXT NOT NULL DEFAULT '{}', schema_json TEXT NOT NULL DEFAULT '{}', landing_json TEXT NOT NULL DEFAULT '{}', state TEXT NOT NULL DEFAULT 'draft', version INTEGER NOT NULL DEFAULT 1, created_at_ms INTEGER NOT NULL, updated_at_ms INTEGER NOT NULL, UNIQUE(domain_uuid, name) ); CREATE TABLE street_spots ( street_uuid TEXT NOT NULL, spot_uuid TEXT NOT NULL UNIQUE, -- one primary Street placement sort_key INTEGER NOT NULL DEFAULT 0, section TEXT NOT NULL DEFAULT '', created_at_ms INTEGER NOT NULL, PRIMARY KEY(street_uuid, spot_uuid) ); CREATE TABLE spot_pages ( spot_uuid TEXT NOT NULL, page_uuid TEXT NOT NULL, edge_type TEXT NOT NULL DEFAULT 'primary', label TEXT NOT NULL DEFAULT '', sort_key INTEGER NOT NULL DEFAULT 0, featured INTEGER NOT NULL DEFAULT 0, source TEXT NOT NULL DEFAULT 'local', created_at_ms INTEGER NOT NULL, PRIMARY KEY(spot_uuid, page_uuid, edge_type) ); CREATE TABLE spot_relations ( source_spot_uuid TEXT NOT NULL, target_spot_uuid TEXT NOT NULL, relation_type TEXT NOT NULL, weight REAL NOT NULL DEFAULT 1.0, created_at_ms INTEGER NOT NULL, PRIMARY KEY(source_spot_uuid, target_spot_uuid, relation_type) ); CREATE TABLE street_inbox_pages ( street_uuid TEXT NOT NULL, page_uuid TEXT NOT NULL, created_at_ms INTEGER NOT NULL, PRIMARY KEY(street_uuid, page_uuid) ); CREATE TABLE topology_events ( id INTEGER PRIMARY KEY AUTOINCREMENT, domain_uuid TEXT NOT NULL, topology_version INTEGER NOT NULL, actor_principal_uuid TEXT NOT NULL, operation TEXT NOT NULL, target_type TEXT NOT NULL, target_uuid TEXT NOT NULL, before_json TEXT NOT NULL DEFAULT '{}', after_json TEXT NOT NULL DEFAULT '{}', request_id TEXT NOT NULL DEFAULT '', created_at_ms INTEGER NOT NULL ); ``` Foreign-key-like invariants are enforced transactionally during compatibility migration and later promoted to SQLite foreign keys when legacy tables can be rebuilt safely. Every Domain has a monotonically increasing topology version. ## Structural invariants - a Zone belongs to exactly one Domain; - a Street has exactly one parent Quartier; - a Quartier is directly owned by its Domain and contains Streets, never other Quartiers or Spots; - a Street points to Spots and temporary Inbox Pages, never child Zones; - a Spot has at most one primary Street placement and no child Spot; - Spot and Page on an edge belong to the same local Domain unless the edge is an explicit external reference; - ZoneTree is acyclic and bounded in depth; - `depends_on` and `learn_before` cycles are rejected or explicitly marked; - the last Page/Spot edge removal never cascades to Page deletion; - archived nodes cannot accept new children or edges; - names are normalized and unique only in their declared scope; UUID is the stable reference used by APIs and relations. ## Policy inheritance The effective policy is evaluated in this order: ```text Domain defaults -> Quartier policy -> Street override -> Spot requirement -> exceptional Page/Object grant ``` Policies remain positive-grant based. A lower locality can require a narrower capability but does not manufacture authority. Curator status is separate from read/write authority, just as group administration is separate from content permissions. Moving a Spot previews any effective-policy change before commit. ## Human-facing projections Knowledge City uses explicit projections so it does not capture ordinary Page paths: | Route | Projection | | --- | --- | | `/v/city` | Domain city map and directory | | `/v/city/q/{quartier-name}` | Quartier detail | | `/v/city/s/{quartier-name}/{street-name}` | Parent-qualified Street detail | | `/v/city/p/{spot-name}` | Spot detail and readable Page links | | `/v/city/{q,s,p}/uuid:{uuid}` | Explicit identity selector, stable across renames | | `/v/city?{quartier,street,spot}={uuid}` | Focus that locality in the map | | `/v/city/changes` | Planned authorized topology activity (not implemented) | Human links use names; mutation APIs use UUIDs. Legacy `/v/city/s/{name}` resolves only a Domain-unique Street name; ambiguous names return 404 rather than selecting an arbitrary parent. Bare UUID-looking names are not UUID selectors. Named URLs follow current names/parents, not historical redirects. A Spot landing can bind an ordinary semantic path when desired; that binding is an explicit, conflict-checked operation. Viewer breadcrumbs can offer two independent trails: - semantic path breadcrumbs; - city locality breadcrumbs (Quartier → Street → Spot). For MagicPages the UI shows the current Spot trail and an authorized “also in” list. It never chooses a fake universal parent. ## Search, discovery and knowledge routes Search accepts locality scopes (`domain`, `quartier`, `street`, `spot`) and filters authorization before aggregation. Results can use list, detail and thumbnail projections already shared by children/search UI. City discovery adds: - nearby knowledge from shared Spot and typed Spot relations; - curated routes and learning sequences; - “missing entrance”, “orphan Page”, “empty Spot”, and stale-area reports; - Page-to-Page route explanation through Spot membership/relation edges; - subscriptions to a Spot, Street or Quartier activity stream; - stable topology context for adapters and future retrieval/agent workloads. Recommendations never silently alter topology. Dynamic/query-backed sections are projections; curator-approved edges are canonical topology. ## Macros Macros read topology through bounded cached projections: ```text {{city}} {{quartier}} {{street}} {{spot}} {{spot-pages edge="guide" view="icon"}} {{nearby relation="depends_on"}} {{city-breadcrumbs}} ``` With no explicit UUID, a macro uses the current authorized locality context. Macro output is asynchronous where expensive, contains no unauthorized counts, and is keyed by Domain topology version plus Principal policy version. ## API surface ```text GET,POST /_/api/v1/city/zones GET,PATCH,DELETE /_/api/v1/city/zones/{uuid} POST /_/api/v1/city/zones/{uuid}/move POST /_/api/v1/city/streets/{uuid}/promote GET,POST /_/api/v1/city/spots GET,PATCH,DELETE /_/api/v1/city/spots/{uuid} GET,POST,DELETE /_/api/v1/city/spots/{uuid}/pages GET,POST,DELETE /_/api/v1/city/spots/{uuid}/relations GET,POST,DELETE /_/api/v1/city/streets/{uuid}/inbox GET /_/api/v1/city/map GET /_/api/v1/city/health GET /_/api/v1/city/events POST /_/api/v1/city/plans/preview POST /_/api/v1/city/plans/apply ``` Mutations use UUIDs, ETag/version preconditions, idempotency keys for bulk plans, CSRF for cookie sessions and topology-targeted capabilities. Preview and apply use the same validated plan payload; apply rejects a changed topology version. ## Caching and indexing - ZoneTree adjacency and breadcrumb cache: keyed by Domain topology version; - SpotGraph adjacency: keyed by Spot version and authorization policy version; - FTS locality fields: localized title, summary, charter keywords and permitted Page content; - health metrics: scheduler jobs with low priority and incremental invalidation; - map/layout/thumbnail: derived cache, never source of truth; - foreground navigation always outranks topology analysis and preview work. ### City geometry adapter Map geometry is a derived projection behind a replaceable `City Geometry Adapter`; it is never topology identity. The built-in adapter accepts the authorized City Map projection and emits Quartier polygons, Street curves and Spot building lots. Generation is deterministic from Domain UUID, topology version and the ordered topology signature. Browser caches are versioned and bounded, so navigation never waits for background geometry generation. An external town generator may replace this adapter when it returns the same neutral geometry contract. Generator-specific IDs must not enter Zone, Spot, Page or Path identity. A later persisted layout layer may pin curator-adjusted coordinates independently of regenerated background parcels. The generator runs once per Domain topology version. Its single road/building fabric is partitioned into contiguous Quartier regions rather than generating and stitching independent towns. Region targets use unique Page UUID weights: Path/primary `1.0`, guide `0.7`, example `0.5`, attachment `0.25`, and reference/related `0.15`. Repeated paths and MagicPage appearances therefore do not multiply physical area. Street road capacity uses the summed weighted Spot membership, while Spots are assigned to buildings nearest their Street segments. Minimum shares prevent empty or new localities from disappearing. Allocation is absolute as well as relative. Weighted Page demand determines the occupied fraction of the generated City; unallocated roads and buildings remain visible but have no Knowledge City owner. Quartiers divide only the occupied region. A Street receives roughly 1.5 generated road segments per weighted Page, with a one-segment minimum, rather than consuming every road in its Quartier. Only when demand approaches generated capacity may the planned localities fill most of the map. ## Federation and inheritance The Domain owning a topology is authoritative. Controller-managed Campus manifests may place or replicate its definition, but two instances do not concurrently edit the same topology without an explicit leader and sequence. Domain PSK identity/group inheritance does not automatically inherit ZoneTree or SpotGraph. A later topology peer policy must opt in separately. Cross-Domain Spot relations carry destination FQDN, Domain UUID, remote Spot UUID and last verified instance fingerprint. They degrade to external links when offline and never create a local writable clone. ## Lifecycle and maintenance Creation starts in `draft`; activation requires valid placement, charter and curator. Deprecation supplies a successor and signage. Archive removes the node from default navigation but preserves stable UUID access for authorized audit. Purge is exceptional, Domain-admin-only, requires no structural references and does not purge Pages. Health rules are advisory except for structural invariants. Suggested initial thresholds are configurable per Domain rather than hard-coded: Page count, staleness interval, broken-link ratio, missing language and unreviewed changes. ## Delivery plan 1. Add topology schema, Domain topology version, stores and invariant tests. 2. Implement Quartier/Street CRUD, map projection and capability target resolvers; no automatic path rewrite. 3. Implement Spot CRUD, primary Street placement and generated landing. 4. Implement SpotPage/MagicPage edges, authorized “also in”, backlinks and city breadcrumbs. 5. Add Spot relations, scoped search, nearby knowledge and route explanation. 6. Add planning preview/apply, Street promotion, split/merge and audit events. 7. Add health scheduler, maintenance queues, subscriptions and topology macros. 8. Add optional signed topology federation only after single-authority behavior and rollback are proven. Each slice requires migration rollback, cross-Domain isolation, authorization, cycle, concurrent-version and cache-invalidation tests.