Vyasa Extension Refactor Audit and Execution Plan

High-Level DiagnosisURL copied

The work took shortcuts in four categories:

Runtime shortcut: extensions are plain modules with META and configure(). They do not implement VyasaExtension.

Registration shortcut: configure(runtime) mutates lists and dicts on ExtensionRuntime directly. That bypasses the restricted app contract and cannot validate that a registration is declared in metadata.

Ownership shortcut: feature renderers still live in vyasa/extensions_builtin/markdown/renderer.py. Mermaid, D2, Cytograph, and Tasks extensions import private functions from Markdown instead of owning their renderers.

Asset shortcut: almost all JavaScript and CSS still lives in vyasa/static/scripts.js and vyasa/static/header.css. Extension folders may have copied assets, but pages still load the global bundle.

2	✦
3	✦ > Documents Read
4	✦ > Contract Baseline
5	✦ > Current Work That Was Done
6	✦ > High-Level Diagnosis
7	✦ > Architecture Decision Framework
8	✦ > Architecture Decision Framework > Deletion Test
9	✦ > Architecture Decision Framework > Real Seams And Hypothetical Seams
10	✦ > Architecture Decision Framework > Dependency Categories For This Refactor
11	✦ > Architecture Decision Framework > Interface Is The Test Surface
12	✦ > Architecture Decision Framework > Design Decisions From The Architecture Skill
13	✦ > Architecture Decision Framework > Deepening Opportunities > 1. Extension Registration Module
14	✦ > Architecture Decision Framework > Deepening Opportunities > 2. Markdown Pipeline Module
15	✦ > Architecture Decision Framework > Deepening Opportunities > 3. Theme Selector Module
16	✦ > Architecture Decision Framework > Deepening Opportunities > 4. Layout Module
17	✦ > Architecture Decision Framework > Deepening Opportunities > 5. Search Module
18	✦ > Architecture Decision Framework > Deepening Opportunities > 6. Bookmark And Annotation Modules
19	✦ > Architecture Decision Framework > Deepening Opportunities > 7. Static Asset Module
20	✦ > Architecture Decision Framework > Deepening Opportunities > 8. Static Build Module
21	✦ > Architecture Decision Framework > Deepening Opportunities > 9. Admin UI Module
22	✦ > Architecture Decision Framework > Deepening Opportunities > 10. Agent Module
23	✦ > Non-Negotiable Rules For The Next Refactor
24	✦ > Current Contract Violations > `VyasaExtension` Does Not Exist
25	✦ > Current Contract Violations > `VyasaExtensionApp` Does Not Exist
26	✦ > Current Contract Violations > Extension Metadata Is Too Weak
27	✦ > Current Contract Violations > Core Still Assigns Default Providers After Runtime Build
28	✦ > Current Contract Violations > Mermaid Extension Does Not Own Mermaid Rendering
29	✦ > Current Contract Violations > D2 Extension Does Not Own D2 Rendering
30	✦ > Current Contract Violations > Cytograph Extension Does Not Own Cytograph Rendering
31	✦ > Current Contract Violations > Tasks Extension Does Not Own Tasks Rendering
32	✦ > Current Contract Violations > Cryptograph Has No Extension
33	✦ > Current Contract Violations > Markdown Renderer Still Has Hard-Coded Fallbacks For Disabled Extensions
34	✦ > Current Contract Violations > Markdown Renderer Imports Extension Implementations
35	✦ > Current Contract Violations > Wikilinks Are Ambiguous In The Current Language
36	✦ > Current Contract Violations > Asset Bundles Are Mostly Fiction
37	✦ > Current Contract Violations > Storage Namespaces Are Not Used
38	✦ > Current Contract Violations > Routes Are Still Core-Owned
39	✦ > Current Contract Violations > `theme_extensions` Is In The Wrong Place
40	✦ > Current Contract Violations > Static Build Is Not Extension-Aware
41	✦ > Current Contract Violations > Tests Validate Metadata, Not Extension Behavior
42	✦ > Target Folder Shape
43	✦ > Target Core Shape
44	✦ > New Contract To Implement > `VyasaExtension`
45	✦ > New Contract To Implement > `VyasaExtensionApp`
46	✦ > New Contract To Implement > Registration Validation
47	✦ > New Contract To Implement > Runtime Freeze
48	✦ > Extension Runtime Build Order
49	✦ > File-Level Audit And Target Ownership > `vyasa/__init__.py`
50	✦ > File-Level Audit And Target Ownership > `vyasa/admin_views.py`
51	✦ > File-Level Audit And Target Ownership > `vyasa/agent.py`
52	✦ > File-Level Audit And Target Ownership > `vyasa/assets.py`
53	✦ > File-Level Audit And Target Ownership > `vyasa/bootstrap.py`
54	✦ > File-Level Audit And Target Ownership > `vyasa/build.py`
55	✦ > File-Level Audit And Target Ownership > `vyasa/config.py`
56	✦ > File-Level Audit And Target Ownership > `vyasa/content_routes.py`
57	✦ > File-Level Audit And Target Ownership > `vyasa/content_tree.py`
58	✦ > File-Level Audit And Target Ownership > `vyasa/core.py`
59	✦ > File-Level Audit And Target Ownership > `vyasa/document_pages.py`
60	✦ > File-Level Audit And Target Ownership > `vyasa/extensions.py`
61	✦ > File-Level Audit And Target Ownership > `vyasa/favicon.py`
62	✦ > File-Level Audit And Target Ownership > `vyasa/file_search.py`
63	✦ > File-Level Audit And Target Ownership > `vyasa/helpers.py`
64	✦ > File-Level Audit And Target Ownership > `vyasa/layout_helpers.py`
65	✦ > File-Level Audit And Target Ownership > `vyasa/layout_page.py`
66	✦ > File-Level Audit And Target Ownership > `vyasa/logging.py`
67	✦ > File-Level Audit And Target Ownership > `vyasa/main.py`
68	✦ > File-Level Audit And Target Ownership > `vyasa/nav_views.py`
69	✦ > File-Level Audit And Target Ownership > `vyasa/page_shell.py`
70	✦ > File-Level Audit And Target Ownership > `vyasa/page_views.py`
71	✦ > File-Level Audit And Target Ownership > `vyasa/rbac_config.py`
72	✦ > File-Level Audit And Target Ownership > `vyasa/rbac_store.py`
73	✦ > File-Level Audit And Target Ownership > `vyasa/runtime_context.py`
74	✦ > File-Level Audit And Target Ownership > `vyasa/search_http.py`
75	✦ > File-Level Audit And Target Ownership > `vyasa/search_pages.py`
76	✦ > File-Level Audit And Target Ownership > `vyasa/search_service.py`
77	✦ > File-Level Audit And Target Ownership > `vyasa/search_views.py`
78	✦ > File-Level Audit And Target Ownership > `vyasa/sidebar_helpers.py`
79	✦ > File-Level Audit And Target Ownership > `vyasa/tree_rendering.py`
80	✦ > File-Level Audit And Target Ownership > `vyasa/tree_service.py`
81	✦ > File-Level Audit And Target Ownership > `vyasa/tree_tables.py`
82	✦ > File-Level Audit And Target Ownership > `vyasa/auth/*`
83	✦ > File-Level Audit And Target Ownership > `vyasa/static/scripts.js`
84	✦ > File-Level Audit And Target Ownership > `vyasa/static/header.css`
85	✦ > File-Level Audit And Target Ownership > `vyasa/static/present.css` And `present.js`
86	✦ > File-Level Audit And Target Ownership > `vyasa/theme_extensions/*`
87	✦ > Built-In Extension Inventory > `markdown`
88	✦ > Built-In Extension Inventory > `tabs`
89	✦ > Built-In Extension Inventory > `mermaid`
90	✦ > Built-In Extension Inventory > `d2`
91	✦ > Built-In Extension Inventory > `cytograph`
92	✦ > Built-In Extension Inventory > `tasks`
93	✦ > Built-In Extension Inventory > `cryptograph`
94	✦ > Built-In Extension Inventory > `slides`
95	✦ > Built-In Extension Inventory > `default_layout`
96	✦ > Built-In Extension Inventory > `themes`
97	✦ > Built-In Extension Inventory > `blog_home`
98	✦ > Built-In Extension Inventory > `default_search`
99	✦ > Built-In Extension Inventory > `bookmarks`
100	✦ > Built-In Extension Inventory > `annotations`
101	✦ > Built-In Extension Inventory > `filesystem`
102	✦ > Built-In Extension Inventory > `documents`
103	✦ > Built-In Extension Inventory > `tree_document`
104	✦ > Built-In Extension Inventory > `pdf_document`
105	✦ > Built-In Extension Inventory > `live_reload`
106	✦ > Built-In Extension Inventory > `code_highlight`
107	✦ > Built-In Extension Inventory > `math`
108	✦ > Built-In Extension Inventory > `embeds`
109	✦ > Mechanical Migration Plan > Phase 0: Freeze Current Behavior
110	✦ > Mechanical Migration Plan > Phase 1: Build The Real Contract
111	✦ > Mechanical Migration Plan > Phase 2: Convert Built-In Registry To Extension Objects
112	✦ > Mechanical Migration Plan > Phase 3: Move Themes Under Built-In Extensions
113	✦ > Mechanical Migration Plan > Phase 4: Extract Diagram Renderers From Markdown
114	✦ > Mechanical Migration Plan > Phase 5: Extract Tasks Rendering From Markdown
115	✦ > Mechanical Migration Plan > Phase 6: Create Cryptograph Extension
116	✦ > Mechanical Migration Plan > Phase 7: Make Markdown A Pure Pipeline Host
117	✦ > Mechanical Migration Plan > Phase 8: Split Global JavaScript Into Extension Assets
118	✦ > Mechanical Migration Plan > Phase 9: Split Global CSS Into Extension Assets
119	✦ > Mechanical Migration Plan > Phase 10: Move Default Layout
120	✦ > Mechanical Migration Plan > Phase 11: Move Blog Home
121	✦ > Mechanical Migration Plan > Phase 12: Move Search
122	✦ > Mechanical Migration Plan > Phase 13: Move Bookmarks Fully
123	✦ > Mechanical Migration Plan > Phase 14: Move Annotations Fully
124	✦ > Mechanical Migration Plan > Phase 15: Move Slides Fully
125	✦ > Mechanical Migration Plan > Phase 16: Move Documents And Document Kinds
126	✦ > Mechanical Migration Plan > Phase 17: Move Filesystem Content Source
127	✦ > Mechanical Migration Plan > Phase 18: Move Default Errors
128	✦ > Mechanical Migration Plan > Phase 19: Move Live Reload
129	✦ > Mechanical Migration Plan > Phase 20: Static Build Parity
130	✦ > Required Tests
131	✦ > Required Tests > Contract Tests
132	✦ > Required Tests > Disabled Behavior Tests
133	✦ > Required Tests > Asset Tests
134	✦ > Required Tests > Cross-Seam Tests
135	✦ > Source-Scanning Gates
136	✦ > Migration Safety Rules For A Small LLM
137	✦ > Concrete First Patch Order
138	✦ > Mermaid Example Target
139	✦ > End-State Acceptance Criteria
140	✦ > Current Biggest Risks
141	✦ > Final Target Mental Model