# Architecture Implementation Roadmap ## Task productivity and private contacts (2026-11-01) - [x] Add idempotent task capture API and neomutt configuration reference. - [x] Extend pages-cli with task planning, start/stop records, reports and private contact lookup. - [x] Add per-user defaults, accomplishment heatmap and opt-in daily SMTP task digest. - [x] Add home search commands with project/calendar suggestions and explicit creation confirmation. - [x] Add private contacts CRUD, trash/restore, vCard import/export and unknown-property preservation. - [ ] Shared address books, CardDAV synchronization, work-record corrections and manual digest retry. See [contracts and remaining scope](ja/task-productivity-contacts.md). These checks describe the implemented slice; production rollout and test evidence are recorded separately. ## Current highest priority (2026-10-31) The user-prioritized [daily UX / browser / editor / CLI backlog](ja/priority-ux-20261031.md) takes precedence over the feature backlog below. It covers type-to-search, virtual Path navigation and browser commands, editor/plain-text and code styling, theme switching, session timeouts, contacts, City labels and a session-aware terminal client. Preserve authorization and storage safeguards. Track implementation, tests and deployment separately; a source checkpoint includes the pre-existing dirty worktree. ## Principles ### Named architecture components (2026-11-01) - [x] Adopt stable responsibility-based names for eight components; preserve UI terminology, public APIs, persisted IDs, event consumer checkpoints and deployment boundaries. - [x] Extract Grammaratur: ordinary and protected authoring conversions, compatibility facades and application connections. Verification is recorded separately from deployment. - [x] Extract Dregarnuhr clock/loop/admission/retry contracts and the queue adapter; register the 14 existing business handlers outside the core. Preserve IDs/schema and atomic claims. - [ ] Add Dregarnuhr expiring leases, fencing, multi-process scheduling and application shutdown integration; these are not provided by the initial extraction. See [contract and remaining work](ja/dregarnuhr.md). - [x] Extract Geduldh local payload storage and bounded materialization; preserve the Document Store contract through aliases, connect application consumers, and test layout/Range/backfill/DR compatibility. External backends and placement changes remain separate work; see [contract and remaining work](ja/geduldh.md). - [x] Extract Mestionora SQLite search/index/City lookup with explicit read-policy callbacks, legacy aliases, candidate/snippet budgets, plan and authorization tests; see [search contract](ja/mestionora.md). - [ ] Preload lazy user-space read policies before Page search; retain snapshot consistency while removing nested connection requirements. Keep current-only/Domain-partitioned and language-aware indexing as later migrations. - [x] Extract Ordoschnellic bounded Web Push dispatch, retry policy and encrypted transport; preserve transactional Inbox enqueue, authorization, event IDs and subscription checkpoints. See [delivery contract and remaining work](ja/ordoschnellic.md). - [ ] Add distinct Push claim generations and subscription-version fencing, Retry-After and delivery metrics. Initial extraction retains existing retry/lease limitations, not exactly-once delivery. - [x] Extract Schutzaria pure Path/locality/group/publication/user-space evaluation and approval state transitions; retain authenticated fact loading, alias checks and transaction ownership in the application. See [policy contract and remaining work](ja/schutzaria.md). - [ ] Complete consistent authorization snapshots, lazy user-space preloading, reviewer inheritance/quorum, and publication revalidation. State-machine extraction alone does not enable the reviewer workflow. - [x] Extract Kunstzeal built-in adapter selection, bounded Kroki rendering and diagram hash/cache; retain source authorization/CSP and add redirect refusal plus atomic cache replacement. See [rendering contract and remaining work](ja/kunstzeal.md). - [ ] Add provider-versioned cache keys, render concurrency/coalescing, unified disable/metrics and additional diagram/slide providers. Initial extraction does not implement nwdiag or slides. - [x] Extract Seheweit resource collection, typed snapshots and history window/retention policy; retain APIs/schema/event IDs, connect foreground and background paths, bound proc reads, guard storage arithmetic, propagate write cancellation and reject read-only sample writes. See [observation contract and remaining work](ja/seheweit.md). - [ ] Add source availability, bounded/coalesced collection, rollups/retention budgets, component/provider metrics and instance-scoped HA/SNMP collectors. These are not part of the initial extraction. See [component names, boundaries and acceptance criteria](ja/component-names.md). All eight initial component extractions are implemented; unchecked items describe remaining capabilities. Released and deployed as [v0.2.0](../operations/deployments/2026-11-01-v0.2.0.md) on 2026-11-01. - [ ] Priority follow-up: eliminate AddEventLog deferred read-to-write transaction contention; preserve atomic raw-log/bucket writes and test independent concurrent writers. Production start-log failures are now observable; job execution succeeded, but log completeness is not guaranteed. ### Storage portability and operations (2026-09-27) Implemented and fixture-tested; included in the [v0.2.0 production release](../operations/deployments/2026-11-01-v0.2.0.md). This does not mark the unchecked backend/HA capabilities below as implemented. - [x] Immutable local Document Store contract, bounded materialization and streaming archive access. - [x] Resumable document backfill with store identity, UUID cursor and batch checkpoints. - [x] SQLite migration ledger with version/checksum, atomic adoption and current-schema assertions. - [x] Managed projection, resource, broadcast, navigation, adapter-session, import and event-queue schemas. - [x] Read-only `pageswiki schema status|check` with JSON output, pending steps and explicit legacy exclusions. - [ ] Remaining legacy schema/repository contracts and context propagation; configurable materialization limits/metrics. - [ ] PostgreSQL/MySQL, S3/SFTP and mounted-store contracts, optional Redis cache. - [ ] Coordinated backup/restore, portable export/import, Web operations and initial setup wizard. See the [Japanese design and acceptance criteria](storage-portability-and-operations.md) and [preflight / deployment procedure](../operations/storage-schema-rollout.md). Passing managed-schema checks does not replace an isolated full-startup rehearsal. ### Task management first slice (2026-09-24) 2026-09-25 task CalDAV (`0.8.0`, implemented and fixture-tested, **deployed to app/app2 on 2026-09-26 at 00:24 JST**; [deployment record](../operations/deployments/2026-09-26-task-caldav.md)): private fixed VTODO collection, revocable read/read-write app passwords with UI, conditional writes and archive deletion. Real vdirsyncer 0.21.0 / Todoman 4.7.0 discovery and bidirectional sync tests. Date-only deadlines; not full CalDAV conformance. See [task CalDAV contract and CLI setup](ja/task-caldav.md). 2026-09-25 task follow-up (`0.7.0`, implemented and deployed to app/app2 at 07:07 JST): daily/tomorrow planning, explicit carryover rescheduling, hierarchy-aware pagination and parent context, and atomic Wiki-note creation with UUID-bound view/edit actions. See [daily task / Wiki note contract](ja/task-daily-notes.md). Capacity, bulk family planning, manual sorting and shared tasks remain open. 2026-09-25 follow-up (implemented, fixture-tested and **deployed to app/app2 at 05:59 JST**; [deployment record](../operations/deployments/2026-09-25-active-notifications-calendar-mobile.md)): - [x] Inline title/status/date editing, independently dated two-level subtasks, bounded monthly day schedule, home shortcut and Today navigation modal (`0.6.0`). - [x] Inbox presentation preferences per account/browser, focused expiring toasts, opt-in return modal, sound presets/volume, notification-only Service Worker. - [x] Opt-in Web Push: transactional Inbox outbox, revocable session-bound subscriptions, VAPID, vendor allowlist/DNS pinning, bounded scheduler delivery/retry/expiry and focus acknowledgements. - [ ] Live OS/browser delivery acceptance with an explicitly opted-in test device (Chrome/Firefox/Safari), iOS home-screen installation and OS power-saving behavior. See [active notification contract](ja/active-notifications.md) and [inline task/day schedule contract](ja/task-inline-schedule.md). - [x] `organizer.tasks` private per-principal/Domain items and projects, CAS payloads, atomic head/revision/change journal, conditional writes and idempotent creation. - [x] Today, Inbox, Backlog, Someday, Review, Completed and Archive; project/task detail, quick capture, due/planned/review dates, priority, estimate and readable Wiki UUID links. - [x] Bounded lists/history, EN/JA, theme-aware desktop/mobile dialogs, extension kill switch. - [x] Typed independent outbox subscriptions; atomic task/project events, bounded journal migration through the scheduler, no City jobs for task-only changes. - [ ] Shared collections/assignees, export/recovery and bulk review. - [x] Opt-in due/planned-date task reminders, atomic reservations/cancellation, bounded background Inbox delivery, live metadata authorization and badge refresh. - [x] Private local calendar time-block links, durable retry intents, current event time/ETag lookup, unlink tombstones; imported/shared/public calendars excluded. - [x] Persistent Pomodoro: start/pause/resume/finish/cancel, one active session per principal, conditional transitions, bounded scheduler completion and Inbox notification. - [x] Today bounded estimates/current local time blocks/recorded focus intervals, overlap and incomplete-total indicators. Calendar event summaries include an explicitly approved task-title snapshot, never notes. - [ ] Personal capacity, carry-over and period/project reports; historical focus-span backfill; calendar reminders, notification defaults/quiet hours/digests; Pomodoro personal defaults/cycles and routines. See [time-block and Pomodoro contracts](ja/task-planning-focus.md) for API, privacy, two-store recovery, polling limits and remaining work. Canonical calendars and task DB metadata both require backup. Production app/app2 deployment completed on 2026-09-25 JST; see the [deployment record](../operations/deployments/2026-09-25-task-today.md) for backup, verification and the observed transient scheduler lock contention. - [x] Limited private VTODO / CalDAV with vdirsyncer + Todoman file synchronization. - [ ] Time-of-day deadlines, recurrence/alarms, shared task collections, incremental sync-token and additional CalDAV clients; dependency graph, tickets and offline UI. See [Japanese task implementation contract](ja/tasks-implementation.md). The existing `/v/plan` calendar default is unchanged; tasks start at `/v/plan/today`. ### Calendar subproject (2026-09-22) - [x] Small-screen/touch calendar navigation, readable week columns and day selector, scroll-first gestures, compact month counts and VisualViewport-aware editor. [Mobile contract](ja/calendar-mobile.md): fixture-tested and deployed 2026-09-25; iPhone Safari acceptance pending. - [x] Initial file-canonical calendar/month snapshots, rebuildable SQLite index, conditional event CRUD and bounded CalDAV time-range REPORT. - [x] `/v/plan` year/month/week/day/events/timeline, event dialogs and per-calendar collaborators. - [x] Per-user default calendar overlays and explicit comma-separated `pretty_name` selection. - [x] Week/day time grids, configured-timezone day boundaries, zoom through 400% with 5-minute precision, ETag-protected move/start/end resizing without refetch, equal overlap lanes, drag-range creation, horizontal rescheduling and `week/list`. - [x] Read-only ICS polling with interval/conditional GET and bounded external CalDAV REPORT/multiget; background event queue, encrypted Basic credentials, SSRF guards and failure-safe snapshots. - [x] Outlook published-ICS projection for METHOD:PUBLISH, VTIMEZONE/TZID, Windows timezone names, bounded RRULE expansion, EXDATE/RDATE, moved/cancelled RECURRENCE-ID instances and orphaned exception projections, plus multi-megabyte synthetic fixtures. - [ ] Recurrence PERIOD/THISANDFUTURE, alarms/durations, provider validation, discovery/OAuth, configurable synchronization windows and conflict-aware bidirectional synchronization. - [ ] Full iCalendar temporal semantics (recurrences, timezones, exceptions), CalDAV discovery/client compatibility, application credentials, synchronization tokens and maintenance/metrics jobs. - [ ] Group sharing, audited administration, ownership recovery and calendar scheduling/notifications. See [Japanese implementation contract and limitations](ja/calendar-implementation.md). The initial supported subset is not a claim of full CalDAV conformance. System-service plugins are distinct from document adapters. See [System extensions](system-extensions.md) for implementation boundaries and the next slices. - [x] Responsive wider bookmark-card grid (viewport-dependent columns). - [x] Built-in resource.sample event, SQLite history, retention and bounded graphs without foreground collection. - [x] Separate system-extension catalog and settings area for trusted built-ins. - [x] Unified execution/resource monitor (running jobs only), paginated job history with lazy logs. - [x] Protect group owners from ordinary member downgrades and atomically retain an owner during concurrent removal. - [ ] Transactional activity outbox and Domain/principal recent-edit projections. - [x] Diary/blog initial built-ins: Page UUID metadata, calendar/recent entries, categories, read-filtered indices, per-Domain enable/disable and registration UI. See [initial scope](diary-blog-plugins.md); this is authenticated, existing-Page registration only. - [x] Diary/blog atomic Markdown new-post composition, transactional metadata/Revision, embedded-asset freezing, idempotent retry and create/write enforcement. - [ ] Diary/blog: anonymous metadata approval/feeds, recent comments and safe resumable tDiary import; declarative time/OS/sunset theme rules. - [x] Diary/blog per-Domain prefixes, optional keyword URL planner, multiple articles per day, and authenticated Domain-root diary/blog entry view (2026-09-17). Legacy Page registration remains available. - [x] Domain entry-settings dialog and signed manifest v2 provisioning of layout, diary/blog enablement and prefixes; atomic destination apply and managed edit guards. - [x] Signed enrollment capability proof and Campus-wide approved-peer v2 preflight before entry-setting changes; unknown/legacy peers block with a visible explanation. - [ ] Entry provisioning inside Domain creation, controlled-settings release/retention, applied-setting acknowledgments and freshness policy. - [x] Diary/blog dated viewer routes `/v/{kind}/yyyy/mm[/dd]`, `own` presence filter, legacy-query redirects, and canonical calendar/filter/pagination navigation. - [x] Local same-Campus diary/blog index/calendar projection without copying articles; source and destination read-policy filtering, source body/edit links, target write guard. - [ ] Project article bodies on destination host, approved anonymous projection, cross-instance source transport/revocation and source-setting federation. - [ ] Rankings, reactions and moderated Page/inline comment services. - [ ] Linkding-compatible bookmark-source injection with scoped credentials. - [ ] Explicit external-search fallback and PagesWiki/GROWI/PukiWiki connectors. - [ ] S3-compatible Document Store; read-only WebDAV/SSH external collections. - [ ] Optional SNMP resource collector with target/OID allowlists and SNMPv3 secrets. - [ ] Third-party system-plugin signature validation, isolated runtime and lifecycle operations. vim.wasm runtime fixes are on hold by user request; its existing configuration UI is retained. ### Prioritized execution order (2026-09-14) Feature checkboxes above are not an instruction to bypass the hardening gates. The execution order is maintained in [Implementation status](implementation-status.md#ordered-next-work). 1. Completed this slice: unified monitor/history UI, bounded/indexed job/log retrieval; first P0 correction: owner downgrade and concurrent last-owner removal protection. 2. Completed bounded hardening: OIDC/JWKS, inherited-admin revocation, browser mutation/purpose checks, Domain/Object scope and read filtering; see the [execution ledger](hardening-execution-2026-09.md). 3. Completed recursive authorized snapshots, literal prefix transactions and signed manifest/checkpoint atomicity. Remaining write-policy fencing and content-author trust are gates before public/shared collaboration. 4. Completed PDF/archive metadata jobs, bounded read-policy snapshots, Object/Revision pagination and improved search; continue lazy City/directory projection, decoder isolation and durable entry extraction. 5. Transactional activity outbox, actor attribution, idempotent URL reconciliation and recent-edit projections. 6. Diary/widgets/import and themes, then comments/rankings, external search/bookmarks, storage connectors and SNMP. HA leases/fencing gate multi-node deployment; external plugin installation remains disabled until isolation/security gates pass. - Migrations must preserve existing UUID and path reachability. - New architecture is introduced in vertical slices with regression tests. - Reserved authorization features must not be simulated with insecure allow-all placeholders. - New collaboration and extension features must use the stable Page UUID, immutable Revision, Domain-scoped policy, projection-adapter, event, and scheduler contracts described in [Platform Extension Architecture](platform-extension-architecture.md). - SQLite remains a supported single-node metadata backend. HA work must add a replicated metadata strategy or explicit single-writer fencing; sharing a live SQLite file over a network filesystem is not an HA design. ## Phase 1 — Identity and projection foundations - [x] Separate Object creation from Semantic Path binding. - [x] Rename the implemented District model to Domain. - [x] Separate Revision UUID from Document SHA-256. - [x] Add Revision language metadata and fallback selection. - [x] Move immutable payloads to `documents/sha256/` with a transitional SQLite compatibility cache. - [x] Add rsync-like and interactive `path:` / `uuid:` / `rev:` / `asset:` data administration. ## Phase 2 — Knowledge City topology Current review: [City reconciliation and navigation](city-review-and-reconciliation.md). The completed items below are initial implementations. The next City slices are: - [x] Audit City/autoplan/gen-city and design URL-driven event reconciliation. - [x] CITY-A named links: parent-qualified Street URLs, ambiguity-safe lookup, shared search/map/macro links, ancestor authorization, lightweight details, literal Page URLs and map focus/locality-search regression coverage. - [ ] CITY-A: per-result authorization, literal Paths, scoped links/names, shallow/portal inference, manual ownership and idempotent application. - [ ] CITY-B: transactional mutation outbox → debounced, durable City queue consumer; scheduled/manual repair through the same pipeline. - [ ] CITY-C: stable fabric, Worker/cache, connected roads, bounded lazy projection and capacity-safe picking targets. - [ ] CITY-D: icon/modal creation/settings, arrow/WASD/HJKL navigation, focus/history handling and i18n browser regressions. - [x] City label follow-up: visible resting labels, horizontal Street names, retained hover/focus highlighting and working label toggle; normal/popup tests. - [x] Manual City organization: display-title modal, Ctrl/Command selection, existing/new Spot merge, Street relocation retaining Page URLs, transactional validation and manual-inference overrides; see [contract](city-organization-ui.md). - [x] Immersive City follow-up: focused Spot courtyards and surrounding Page buildings, nonoverlapping bounded/paginated close-ups, themed architectural SVG, modal utility menu and directory navigation; normal/popup regressions. See [projection and limits](city-immersive-map.md); CITY-A–D gates remain open. - [x] Filter City map/details/macros/badges by readable boundaries and Pages; recompute visible portals/counts/relations and use private responses. - [x] Local gen-city Worker with time/input/output/cache bounds, cancellation and retry, plus spatial Arrow/WASD/HJKL navigation in normal/popup modes; see [worker and navigation](city-worker-navigation.md). - [x] One-connection-safe bounded City snapshots and literal Path containment/overlap/context/health; true lazy Page pagination remains open. - [x] Define Campus identity and defaults. - [x] Define Domain ownership by Campus. - [x] Scope Semantic Paths by `(domain_uuid, path)`. - [x] Add local/remote Domain placement. - [x] Add absolute cross-Domain link helpers. - [x] Add standalone/controller/managed Campus authority modes. - [x] Scope non-topology configuration by Domain. - [x] Scope Recent Objects by selected Campus and Domain. - [x] Record controller-selected Domain instance FQDN. - [x] Add hashed enrollment tokens and fingerprinted instance registration. - [x] Add pending/approved/revoked instance placement selection. - [x] Add external Campus bootstrap enrollment. - [x] Add Managed Campus health status and detach actions. - [x] Add signed Campus manifest reconciliation. - [x] Implement ZoneTree nodes for Quartier and Street. - [x] Implement Spot identity and ZoneTree pointers. - [x] Implement SpotGraph Page bindings and MagicPage traversal. - [x] Define Quartier planning, Street routing, Spot locality, topology invariants, projections, APIs, policy inheritance, and delivery slices. - [x] Add the initial topology schema, monotonic Domain topology version, topology events, and Quartier/Street/Spot creation stores. - [x] Add the initial interactive `/v/city` SVG guide map and authorized map API. - [x] Add SpotPage/MagicPage edges, Viewer locality badges, Spot detail Page lists, and initial typed SpotGraph relation visualization. - [x] Add Quartier/Street/Spot detail projections, transactional Street/Spot moves, ordering, and reversible SpotPage/SpotRelation edge removal. - [x] Add planning preview/apply, reversible before/after event payloads, and city health analysis. - [x] Add `/v/city` map and locality breadcrumbs. - [x] Add locality-scoped search and topology macros. ## Phase 3 — Projection runtime - [x] Formalize the initial Viewer projection adapter registry and contract. - [x] Route Viewer and semantic editor selection through adapters. - [x] Route preview through adapters, including bounded text and CSV projections. - [x] Route bounded print layouts through adapters at `/_/view/print/
`. - [x] Route the semantic Viewer through the initial adapter registry. - [x] Add bounded text retrieval backed by seekable Document Store reads. - [x] Defer PDF page rendering to idempotent scheduler jobs with retrying Viewer delivery and bounded PDF page-count commands. - [ ] Defer non-ZIP archive metadata and entry extraction to cached, bounded scheduler projections. - [x] Persist PDF page-count and non-ZIP metadata via shared scheduler jobs, bounded immutable-hash cache and localized pending/retry views. - [ ] Persist seekable non-ZIP extracted entries with quota/lease/Range and archive-bomb controls; move ZIP central-directory work off the request path. - [x] Add bounded structural JSON retrieval by immutable Revision and lazy JSON-Pointer expansion without unmarshalling the complete payload. - [x] Separate authoring and projection macro transpilation so HTML-to-Markdown round trips preserve `children` while Markdown previews render it. - [ ] Generalize the authoring/projection macro contract to typed extension macros with versioned round-trip and projection tests. - [x] Add ZIP/archive directory and Debian metadata adapters. - [x] Add a bounded CSV table adapter. - [x] Add the bounded `@excalidraw/excalidraw` hosted Viewer plugin with an isolated immutable-Revision contract and safe built-in Canvas fallback. - [x] Separate built-in projections from Domain-scoped hosted adapter plugins. - [x] Restrict hosted adapter targets to HTTP(S) services such as vim.wasm or a separately deployed editor gateway. - [x] Define and implement one-use launch tickets and optimistic Revision write-back with a reference hosted-editor gateway. - [x] Connect an internal code-server instance to the hosted-editor Gateway, with session workspace materialization and autosave Revision write-back. - [x] Connect a cross-origin-isolated vim.wasm frontend to the hosted-editor Gateway contract with hierarchical MEMFS loading and Revision write-back. - [ ] Evaluate a local helper, temporary workspace, and executable allowlist before enabling native applications such as Vim or VS Code. - [x] Freeze embedded mutable Asset HEADs into immutable Document hashes on Revision save and retain authorization references from the containing Page. - [x] Scope mutable Asset addresses and management metadata by Domain. - [x] Add typed Asset MIME/filename/size metadata and immutable HEAD history. - [x] Add administrator HTTP create/update/delete with ETag preconditions. - [x] Add the initial Asset management panel under Domain configuration. - [x] Add Asset HEAD history/restore and Page/Revision dependency-detail UI. - [ ] Add Asset retention controls, policy-matrix capabilities, and general audit-outbox integration as specified in `asset-model.md`. - [ ] Add a capability-checked mutable Asset authoring-preview endpoint and typed `srcset`/CSS resource resolution without allowing live Asset URLs into stored Viewer output. - [x] Add authorized immutable object retrieval at `/_/obj/sha256: