amalfa 1.0.2 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/package.json +1 -1
  2. package/src/cli.ts +1 -1
  3. package/docs/AGENT-METADATA-PATTERNS.md +0 -1021
  4. package/docs/AGENT_PROTOCOLS.md +0 -28
  5. package/docs/ARCHITECTURAL_OVERVIEW.md +0 -123
  6. package/docs/BENTO_BOXING_DEPRECATION.md +0 -281
  7. package/docs/Bun-SQLite.html +0 -464
  8. package/docs/COMMIT_GUIDELINES.md +0 -367
  9. package/docs/CONFIG_E2E_VALIDATION.md +0 -147
  10. package/docs/CONFIG_UNIFICATION.md +0 -187
  11. package/docs/CONFIG_VALIDATION.md +0 -103
  12. package/docs/DEVELOPER_ONBOARDING.md +0 -36
  13. package/docs/Graph and Vector Database Best Practices.md +0 -214
  14. package/docs/LEGACY_DEPRECATION.md +0 -174
  15. package/docs/MCP_SETUP.md +0 -317
  16. package/docs/PERFORMANCE_BASELINES.md +0 -88
  17. package/docs/QUICK_START_MCP.md +0 -168
  18. package/docs/REPOSITORY_CLEANUP_SUMMARY.md +0 -261
  19. package/docs/SESSION-2026-01-06-METADATA-PATTERNS.md +0 -346
  20. package/docs/SETUP.md +0 -464
  21. package/docs/SETUP_COMPLETE.md +0 -464
  22. package/docs/VISION-AGENT-LEARNING.md +0 -1242
  23. package/docs/_current-config-status.md +0 -93
  24. package/docs/edge-generation-methods.md +0 -57
  25. package/docs/elevator-pitch.md +0 -118
  26. package/docs/graph-and-vector-database-playbook.html +0 -480
  27. package/docs/hardened-sqlite.md +0 -85
  28. package/docs/headless-knowledge-management.md +0 -79
  29. package/docs/john-kaye-flux-prompt.md +0 -46
  30. package/docs/keyboard-shortcuts.md +0 -80
  31. package/docs/opinion-proceed-pattern.md +0 -29
  32. package/docs/polyvis-nodes-edges-schema.md +0 -77
  33. package/docs/protocols/lab-protocol.md +0 -30
  34. package/docs/reaction-iquest-loop-coder.md +0 -46
  35. package/docs/services.md +0 -60
  36. package/docs/sqlite-wal-readonly-trap.md +0 -228
  37. package/docs/strategy/css-architecture.md +0 -40
  38. package/docs/test-document-cycle.md +0 -83
  39. package/docs/test_lifecycle_E2E.md +0 -4
  40. package/docs/the-bicameral-graph.md +0 -83
  41. package/docs/user-guide.md +0 -70
  42. package/docs/vision-helper.md +0 -53
package/docs/graph-and-vector-database-playbook.html DELETED
@@ -1,480 +0,0 @@
1
- <!DOCTYPE html>
2
- <html lang="en">
3
- <head>
4
- <meta charset="UTF-8">
5
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
- <title>The Hybrid Graph-Vector-SQL Playbook</title>
7
- <script src="https://cdn.tailwindcss.com"></script>
8
- <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
9
- <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;600;800&display=swap" rel="stylesheet">
10
- <style>
11
- body { font-family: 'Inter', sans-serif; }
12
-
13
- .chart-container {
14
- position: relative;
15
- width: 100%;
16
- max-width: 600px;
17
- margin-left: auto;
18
- margin-right: auto;
19
- height: 350px;
20
- max-height: 400px;
21
- }
22
-
23
- .connector-vertical {
24
- width: 2px;
25
- height: 20px;
26
- background-color: #cbd5e1;
27
- margin: 0 auto;
28
- }
29
-
30
- ::-webkit-scrollbar {
31
- width: 8px;
32
- }
33
- ::-webkit-scrollbar-track {
34
- background: #f1f1f1;
35
- }
36
- ::-webkit-scrollbar-thumb {
37
- background: #888;
38
- border-radius: 4px;
39
- }
40
- ::-webkit-scrollbar-thumb:hover {
41
- background: #555;
42
- }
43
- .signal-bar {
44
- height: 10px;
45
- border-radius: 9999px;
46
- transition: width 0.5s ease-in-out;
47
- }
48
- </style>
49
- </head>
50
- <body class="bg-slate-50 text-slate-700">
51
-
52
- <header class="bg-slate-900 text-white py-16 px-4">
53
- <div class="max-w-5xl mx-auto text-center">
54
- <h1 class="text-4xl md:text-6xl font-extrabold tracking-tight mb-4">
55
- <span class="text-indigo-400">Graph</span> + <span class="text-cyan-400">Vector</span> + <span class="text-fuchsia-400">SQL</span>
56
- <br>The Hybrid Playbook
57
- </h1>
58
- <p class="text-xl md:text-2xl text-slate-300 max-w-3xl mx-auto font-light">
59
- Engineering principles for high-S/N, deterministic data systems: Constrained from Ingestion to Synthesis.
60
- </p>
61
- <div class="mt-8 flex justify-center gap-4 flex-wrap">
62
- <div class="bg-slate-800 p-4 rounded-lg border-l-4 border-indigo-500 shadow-lg">
63
- <p class="text-xs text-slate-400 uppercase tracking-wider">Input Control</p>
64
- <p class="text-2xl font-bold">Retrieval Heuristic</p>
65
- </div>
66
- <div class="bg-slate-800 p-4 rounded-lg border-l-4 border-cyan-500 shadow-lg">
67
- <p class="text-xs text-slate-400 uppercase tracking-wider">Document KPI</p>
68
- <p class="text-2xl font-bold">Graph Structure</p>
69
- </div>
70
- <div class="bg-slate-800 p-4 rounded-lg border-l-4 border-fuchsia-500 shadow-lg">
71
- <p class="text-xs text-slate-400 uppercase tracking-wider">Output Control</p>
72
- <p class="text-2xl font-bold">CTX Persona</p>
73
- </div>
74
- </div>
75
- </div>
76
- </header>
77
-
78
- <main class="max-w-6xl mx-auto px-4 py-12 space-y-24">
79
-
80
- <!-- SECTION 1: DETERMINISTIC ENGINEERING -->
81
- <section>
82
- <div class="mb-8">
83
- <h2 class="text-3xl font-bold text-slate-900 mb-2 border-l-8 border-cyan-500 pl-4">1. Engineering Focus: Determinism for High S/N</h2>
84
- <p class="text-lg leading-relaxed max-w-4xl">
85
- The core engineering principle is to maximize the Signal-to-Noise (S/N) ratio from the very start. We achieve this by favoring deterministic, scripted transformations over non-deterministic, high-cost LLM generation steps. This ensures the pipeline is **repeatable**, **tunable**, and **verifiable**.
86
- </p>
87
- </div>
88
-
89
- <div class="grid grid-cols-1 md:grid-cols-3 gap-6">
90
-
91
- <div class="bg-white p-6 rounded-xl shadow-md border-t-4 border-cyan-500">
92
- <h3 class="text-xl font-bold mb-3 text-cyan-700">Scripted Transformation (Signal)</h3>
93
- <p class="text-sm text-slate-600 mb-4">A simple 5-line script can accomplish explicit tasks with "cool calm detachment," providing maximum signal fidelity. Use scripts for parsing, data cleansing, and explicit relationship mapping.</p>
94
- <p class="font-bold mt-2">S/N Impact:</p>
95
- <ul class="list-disc pl-5 text-sm text-slate-500">
96
- <li>Noise Filter: Excellent</li>
97
- <li>Verifiability: 100%</li>
98
- <li>Cost/Latency: Low</li>
99
- </ul>
100
- </div>
101
-
102
- <div class="bg-white p-6 rounded-xl shadow-md border-t-4 border-red-500">
103
- <h3 class="text-xl font-bold mb-3 text-red-700">LLM Generation (Potential Noise)</h3>
104
- <p class="text-sm text-slate-600 mb-4">Reserve LLMs strictly for tasks requiring genuine inference, creativity, or deep semantic interpretation (e.g., generating node descriptions). This minimizes expensive, unpredictable steps.</p>
105
- <p class="font-bold mt-2">S/N Impact:</p>
106
- <ul class="list-disc pl-5 text-sm text-slate-500">
107
- <li>Noise Filter: Poor</li>
108
- <li>Cost/Latency: High</li>
109
- <li>Use Case: Inference Only</li>
110
- </ul>
111
- </div>
112
-
113
- <div class="bg-white p-6 rounded-xl shadow-md border-t-4 border-indigo-500">
114
- <h3 class="text-xl font-bold mb-3 text-indigo-700">Pipeline Qualities</h3>
115
- <p class="text-sm text-slate-600 mb-4">The combination of modular design and deterministic scripting allows the pipeline to be high S/N, idempotent, repeatable, and easily verified against expected output.</p>
116
- <p class="font-bold mt-2">Key Attributes:</p>
117
- <ul class="list-disc pl-5 text-sm text-slate-500">
118
- <li>**Idempotent:** Rerun without side effects.</li>
119
- <li>**Tunable:** Easy parameter modification.</li>
120
- <li>**Repeatable:** Consistent results across runs.</li>
121
- </ul>
122
- </div>
123
-
124
- </div>
125
- </section>
126
-
127
- <!-- SECTION 2: CRITICAL INGESTION & S/N RATIO -->
128
- <section>
129
- <div class="mb-8">
130
- <h2 class="text-3xl font-bold text-slate-900 mb-2 border-l-8 border-fuchsia-500 pl-4">2. Ingestion Pipeline: High S/N Ratio & Early Tuning</h2>
131
- <p class="text-lg leading-relaxed max-w-4xl">
132
- By maximizing deterministic steps, the pipeline minimizes noise from the outset. This allows for the critical tuning of semantic link generation much earlier. The **Bento Box Protocol** and **Louvain Constraint** (Max 7) are the core S/N boosters.
133
- </p>
134
- </div>
135
-
136
- <div class="grid grid-cols-1 md:grid-cols-3 gap-8 items-start">
137
-
138
- <div class="md:col-span-2 bg-white p-6 rounded-xl shadow-md border-t-4 border-fuchsia-500">
139
- <h3 class="text-xl font-bold mb-4">The Bento Box Protocol for S/N Optimization</h3>
140
-
141
- <div class="flex justify-between items-center text-sm font-bold text-slate-600 mb-4">
142
- <span>Ingestion Quality (0% - 100%)</span>
143
- <span>Resulting S/N Ratio</span>
144
- </div>
145
-
146
- <div class="mb-6 space-y-4">
147
- <div class="flex items-center gap-4">
148
- <div class="w-1/3 font-semibold">Standard Chunking (Noise)</div>
149
- <div class="w-2/3 flex items-center">
150
- <div class="signal-bar bg-red-400" style="width: 30%;"></div>
151
- <span class="ml-4 text-sm font-mono text-red-600">Low (30%)</span>
152
- </div>
153
- </div>
154
- <div class="flex items-center gap-4">
155
- <div class="w-1/3 font-semibold">AST-Grep (Signal)</div>
156
- <div class="w-2/3 flex items-center">
157
- <div class="signal-bar bg-green-500" style="width: 85%;"></div>
158
- <span class="ml-4 text-sm font-mono text-green-700">High (85%+)</span>
159
- </div>
160
- </div>
161
- </div>
162
-
163
- <div class="p-4 bg-slate-50 rounded border border-slate-200">
164
- <h4 class="font-bold text-lg text-slate-800 mb-2">Louvain Constraint for Coherence</h4>
165
- <p class="text-sm text-slate-600">
166
- Restricting communities to Max 7 (Miller's Law) ensures the Agentic traversal is efficient and focused. This prevents the Agent from getting lost in a complex graph with an ambiguous, fractured narrative.
167
- </p>
168
- </div>
169
- </div>
170
-
171
- <div class="bg-slate-100 p-6 rounded-xl border border-slate-200">
172
- <h3 class="text-lg font-bold text-center text-slate-800 mb-4">Bento Box Flow</h3>
173
-
174
- <div class="flex flex-col items-center">
175
- <div class="bg-indigo-600 text-white p-3 rounded-lg text-sm font-bold shadow-md">Markdown Source</div>
176
- <div class="connector-vertical bg-indigo-300"></div>
177
- <div class="bg-indigo-500 text-white p-3 rounded-lg text-sm font-bold shadow-md">AST-Grep Parse (Scripted)</div>
178
- <div class="connector-vertical bg-cyan-300"></div>
179
- <div class="bg-cyan-500 text-white p-3 rounded-lg text-sm font-bold shadow-md">Logical Chunking (Scripted)</div>
180
- <div class="connector-vertical bg-fuchsia-300"></div>
181
- <div class="bg-fuchsia-500 text-white p-3 rounded-lg text-sm font-bold shadow-md">Link Generation & Pruning (Hybrid)</div>
182
- </div>
183
- </div>
184
- </div>
185
- </section>
186
-
187
- <!-- SECTION 3: ALIGNMENT & CONTROL -->
188
- <section>
189
- <div class="mb-8">
190
- <h2 class="text-3xl font-bold text-slate-900 mb-2 border-l-8 border-indigo-600 pl-4">3. System Alignment: CTX Persona and Retrieval Heuristics</h2>
191
- <p class="text-lg leading-relaxed max-w-4xl">
192
- Effective output requires control over both the input (retrieval) and the processing (synthesis). The **Agentic Retrieval Heuristic** ensures the high S/N context is retrieved, directly supporting the principles defined by the **CTX Persona**.
193
- </p>
194
- </div>
195
-
196
- <div class="grid grid-cols-1 md:grid-cols-2 gap-8 items-stretch">
197
- <!-- CTX Persona & Principles -->
198
- <div class="bg-white p-6 rounded-xl shadow-lg border-t-4 border-cyan-500 flex flex-col justify-between">
199
- <div>
200
- <h3 class="text-xl font-bold mb-3 text-cyan-700">CTX Persona: The Operating System (Output Control)</h3>
201
- <p class="text-sm text-slate-600 mb-4">The Persona constrains the LLM substrate, focusing thought on the user's principles. It dictates the synthesis style and ensures the resulting narrative is grounded and trustworthy.</p>
202
-
203
- <div class="space-y-3">
204
- <div class="p-3 bg-slate-50 rounded border border-slate-200">
205
- <span class="font-bold text-indigo-600">Principles</span>
206
- <p class="text-sm text-slate-700 mt-1">Clarity, Conciseness, Veracity (Auditable Artifacts)</p>
207
- </div>
208
- </div>
209
- </div>
210
- </div>
211
-
212
- <!-- Proposed Heuristic -->
213
- <div class="bg-slate-100 p-6 rounded-xl shadow-lg border-t-4 border-indigo-500 flex flex-col justify-between">
214
- <div>
215
- <h3 class="text-xl font-bold mb-4 text-indigo-700">Agentic Retrieval Heuristic (Tool Use Policy, Input Control)</h3>
216
- <p class="text-sm text-slate-600 mb-4">This operational heuristic is the Agent's strategy for querying the hybrid-DB, ensuring the retrieved context is laser-focussed (high S/N) for synthesis.</p>
217
-
218
- <div class="space-y-3">
219
- <div class="p-3 bg-white rounded border border-slate-200">
220
- <span class="font-bold text-fuchsia-600">IF "How" / "Why"</span>
221
- <p class="text-sm font-mono text-slate-700 mt-1">V $\rightarrow$ G $\rightarrow$ (V+G Context)</p>
222
- </div>
223
- <div class="p-3 bg-white rounded border border-slate-200">
224
- <span class="font-bold text-fuchsia-600">IF "What is the value"</span>
225
- <p class="text-sm font-mono text-slate-700 mt-1">V $\rightarrow$ S $\rightarrow$ (G Context)</p>
226
- </div>
227
- </div>
228
- </div>
229
- <p class="text-xs text-slate-500 mt-4 italic">
230
- The Heuristic ensures the Agent gets "Bang for its Buck" by synthesizing, not sifting.
231
- </p>
232
- </div>
233
- </div>
234
- </section>
235
-
236
- <!-- SECTION 4: VALIDATION: STRUCTURE AS DIAGNOSTIC -->
237
- <section>
238
- <div class="mb-8">
239
- <h2 class="text-3xl font-bold text-slate-900 mb-2 border-l-8 border-fuchsia-500 pl-4">4. Validation: Structure as Diagnostic</h2>
240
- <p class="text-lg leading-relaxed max-w-4xl">
241
- The hybrid architecture is inherently self-diagnostic. If structure is absent after ingestion, the statistics derived from the graph (Louvain modularity, semantic edge frequency) provide precise data points for parameter tuning.
242
- </p>
243
- </div>
244
-
245
- <div class="grid grid-cols-1 md:grid-cols-2 gap-8 items-center">
246
- <div class="bg-white p-6 rounded-xl shadow-md">
247
- <h3 class="text-xl font-bold mb-4 text-center">System Performance Comparison</h3>
248
- <div class="chart-container">
249
- <canvas id="radarChart"></canvas>
250
- </div>
251
- <p class="text-sm text-slate-500 mt-4 text-center italic">
252
- The Poly Hybrid maximizes Hallucination Resistance (due to Graph/SQL constraints) and Semantic Depth.
253
- </p>
254
- </div>
255
-
256
- <div class="bg-white p-6 rounded-xl shadow-lg border-t-4 border-cyan-500">
257
- <h3 class="text-xl font-bold mb-4">Community Density vs. Narrative Coherence</h3>
258
- <div class="chart-container">
259
- <canvas id="communityChart"></canvas>
260
- </div>
261
- <p class="text-sm text-slate-600 mt-4 italic">
262
- The optimized Max 7 community constraint yields the highest coherence score when the Agent is tasked with generating a project history.
263
- </p>
264
- </div>
265
- </div>
266
- </section>
267
-
268
- <!-- SECTION 5: CONCLUSION -->
269
- <section class="bg-slate-100 p-8 md:p-12 rounded-xl shadow-inner">
270
- <h2 class="text-3xl md:text-4xl font-extrabold text-slate-900 mb-6 text-center">
271
- 5. Conclusion: Graph Structure is Document Quality KPI
272
- </h2>
273
- <div class="max-w-4xl mx-auto space-y-6">
274
- <p class="text-xl leading-relaxed text-slate-700 text-center">
275
- The final measure of the entire pipeline—from ingestion to tuning—is the ability to **discern structures in the graph**. The topological output is not just data; it is an auditable metric of the source document set's intrinsic signal quality.
276
- </p>
277
-
278
- <div class="grid grid-cols-1 md:grid-cols-2 gap-6 pt-4">
279
- <div class="bg-white p-6 rounded-lg border-l-4 border-green-500 shadow-md">
280
- <h3 class="font-bold text-xl text-green-700 mb-2">Structure Found: High Signal</h3>
281
- <p class="text-sm text-slate-600">
282
- The Louvain modularity score is high, the semantic edges are logical, and the Agent produces a coherent narrative. The document set is validated as high-fidelity and well-organized.
283
- </p>
284
- </div>
285
- <div class="bg-white p-6 rounded-lg border-l-4 border-red-500 shadow-md">
286
- <h3 class="font-bold text-xl text-red-700 mb-2">No Structure: Document Noise</h3>
287
- <p class="text-sm text-slate-600">
288
- If, after running the idempotent process and tuning all parameters, structure fails to emerge, the implication is clear: **the source document set is fundamentally noise.**
289
- </p>
290
- </div>
291
- </div>
292
- </div>
293
- </section>
294
-
295
- <!-- SECTION 6: PLAYBOOK & BEST PRACTICES (RENUMBERED) -->
296
- <section class="bg-slate-900 text-white -mx-4 px-4 py-16 md:px-12 md:rounded-3xl shadow-2xl">
297
- <h2 class="text-3xl md:text-4xl font-bold mb-8 text-center"><span class="text-transparent bg-clip-text bg-gradient-to-r from-cyan-400 to-indigo-400">6. The Hybrid Playbook: Actionable Checklist</span></h2>
298
-
299
- <div class="grid grid-cols-1 md:grid-cols-3 gap-8">
300
- <!-- Card 1 (Tune S/N) -->
301
- <div class="bg-slate-800 p-6 rounded-xl border border-slate-700 hover:border-cyan-500 transition-colors">
302
- <div class="text-cyan-400 text-3xl mb-4">01</div>
303
- <h3 class="text-xl font-bold mb-3">Tune for High S/N Ratio</h3>
304
- <p class="text-slate-400 text-sm mb-4">Prioritize deterministic scripting (AST-Grep) to eliminate noise early. Use the modular pipeline to iteratively adjust parameters until a high S/N ratio is confirmed.</p>
305
- <div class="bg-slate-900 p-3 rounded text-xs font-mono text-cyan-300">
306
- Goal: Optimize for High S/N From Ingestion
307
- </div>
308
- </div>
309
-
310
- <!-- Card 2 (Agentic Validation) -->
311
- <div class="bg-slate-800 p-6 rounded-xl border border-slate-700 hover:border-fuchsia-500 transition-colors">
312
- <div class="text-fuchsia-400 text-3xl mb-4">02</div>
313
- <h3 class="text-xl font-bold mb-3">Louvain Constraint (Max 7)</h3>
314
- <p class="text-slate-400 text-sm mb-4">Enforce a strict maximum of 7 top-level Louvain communities to align graph complexity with cognitive capacity. Validate this constraint using the Agentic Narrative test.</p>
315
- <div class="bg-slate-900 p-3 rounded text-xs font-mono text-fuchsia-300">
316
- Rule: Community Count $\leq 7$
317
- </div>
318
- </div>
319
-
320
- <!-- Card 3 (Hybrid Retrieval) -->
321
- <div class="bg-slate-800 p-6 rounded-xl border border-slate-700 hover:border-indigo-500 transition-colors">
322
- <div class="text-indigo-400 text-3xl mb-4">03</div>
323
- <h3 class="text-xl font-bold mb-3">Align Input with CTX Persona</h3>
324
- <p class="text-slate-400 text-sm mb-4">Use the Retrieval Heuristic to ensure input context is laser-focused and aligned with the Persona's principles (clarity, veracity) before the Agent begins synthesis.</p>
325
- <div class="bg-slate-900 p-3 rounded text-xs font-mono text-indigo-300">
326
- Heuristic $\rightarrow$ Context $\rightarrow$ Persona
327
- </div>
328
- </div>
329
- </div>
330
- </section>
331
-
332
- </main>
333
-
334
- <footer class="bg-slate-100 py-8 text-center text-slate-500 text-sm">
335
- <p>Generated for the Poly Project &bull; Hybrid Database Architecture Review</p>
336
- </footer>
337
-
338
- <script>
339
- function formatLabel(str, maxwidth) {
340
- if (typeof str !== 'string') return str;
341
- if (str.length <= maxwidth) return str;
342
-
343
- const words = str.split(' ');
344
- const lines = [];
345
- let line = "";
346
-
347
- words.forEach(word => {
348
- if ((line + word).length > maxwidth) {
349
- lines.push(line.trim());
350
- line = word + " ";
351
- } else {
352
- line += word + " ";
353
- }
354
- });
355
- lines.push(line.trim());
356
- return lines;
357
- }
358
-
359
- const commonOptions = {
360
- responsive: true,
361
- maintainAspectRatio: false,
362
- plugins: {
363
- tooltip: {
364
- callbacks: {
365
- title: function(tooltipItems) {
366
- const item = tooltipItems[0];
367
- let label = item.chart.data.labels[item.dataIndex];
368
- if (Array.isArray(label)) {
369
- return label.join(' ');
370
- } else {
371
- return label;
372
- }
373
- }
374
- }
375
- },
376
- legend: {
377
- labels: {
378
- font: { family: 'Inter', size: 12 },
379
- usePointStyle: true,
380
- color: '#475569'
381
- }
382
- }
383
- }
384
- };
385
-
386
- const ctxRadar = document.getElementById('radarChart').getContext('2d');
387
- const radarLabels = ["Narrative Context", "Hallucination Resistance", "Data Freshness (SQL)", "Query Flexibility", "Semantic Depth"];
388
- const wrappedRadarLabels = radarLabels.map(l => formatLabel(l, 16));
389
-
390
- new Chart(ctxRadar, {
391
- type: 'radar',
392
- data: {
393
- labels: wrappedRadarLabels,
394
- datasets: [
395
- {
396
- label: 'Poly Hybrid (G+V+SQL)',
397
- data: [95, 95, 90, 90, 95],
398
- fill: true,
399
- backgroundColor: 'rgba(79, 70, 229, 0.2)',
400
- borderColor: '#4f46e5',
401
- pointBackgroundColor: '#4f46e5',
402
- pointBorderColor: '#fff',
403
- pointHoverBackgroundColor: '#fff',
404
- pointHoverBorderColor: '#4f46e5'
405
- },
406
- {
407
- label: 'Standard Vector RAG',
408
- data: [50, 40, 60, 60, 70],
409
- fill: true,
410
- backgroundColor: 'rgba(6, 182, 212, 0.2)',
411
- borderColor: '#06b6d4',
412
- pointBackgroundColor: '#06b6d4',
413
- pointBorderColor: '#fff'
414
- },
415
- {
416
- label: 'Pure Knowledge Graph',
417
- data: [80, 85, 20, 30, 40],
418
- fill: true,
419
- backgroundColor: 'rgba(148, 163, 184, 0.2)',
420
- borderColor: '#94a3b8',
421
- pointBackgroundColor: '#94a3b8',
422
- pointBorderColor: '#fff'
423
- }
424
- ]
425
- },
426
- options: {
427
- ...commonOptions,
428
- scales: {
429
- r: {
430
- angleLines: { color: '#e2e8f0' },
431
- grid: { color: '#e2e8f0' },
432
- pointLabels: {
433
- font: { family: 'Inter', size: 11 },
434
- color: '#64748b'
435
- },
436
- ticks: { display: false }
437
- }
438
- }
439
- }
440
- });
441
-
442
- const ctxBar = document.getElementById('communityChart').getContext('2d');
443
- const barLabels = ["Unconstrained Graph", "Optimized (Max 7)", "Over-Pruned (Max 3)"];
444
- const wrappedBarLabels = barLabels.map(l => formatLabel(l, 16));
445
-
446
- new Chart(ctxBar, {
447
- type: 'bar',
448
- data: {
449
- labels: wrappedBarLabels,
450
- datasets: [{
451
- label: 'Agent Narrative Coherence Score (0-100)',
452
- data: [45, 92, 60],
453
- backgroundColor: [
454
- '#94a3b8',
455
- '#d946ef',
456
- '#cbd5e1'
457
- ],
458
- borderRadius: 6
459
- }]
460
- },
461
- options: {
462
- ...commonOptions,
463
- scales: {
464
- y: {
465
- beginAtZero: true,
466
- max: 100,
467
- grid: { color: '#f1f5f9' },
468
- ticks: { font: { family: 'Inter' } }
469
- },
470
- x: {
471
- grid: { display: false },
472
- ticks: { font: { family: 'Inter' } }
473
- }
474
- }
475
- }
476
- });
477
-
478
- </script>
479
- </body>
480
- </html>
package/docs/hardened-sqlite.md DELETED
@@ -1,85 +0,0 @@
1
- To build a hardened, multi-process SQLite system within the Bun ecosystem, we must move beyond standard configurations and address the physical "territory" of the file system and the locking mechanics of the WAL (Write-Ahead Logging) mode.
2
-
3
- The following "belt and braces" recipe implements **Deductive Minimalism (COG-12)**—subtracting potential failure points like `mmap` and directory permission ambiguities—to achieve **Workflow Durability (PHI-13)**.
4
-
5
- -----
6
-
7
- ## 1\. File System "Territory" Requirements
8
-
9
- SQLite in WAL mode is not a single file; it is a triad. Your OS permissions must reflect this, or you will encounter `SQLITE_READONLY` even with `readonly: false` in your code.
10
-
11
- * **The Directory:** The parent folder must have **Write + Execute** permissions for all participating processes (Writer and Readers) to allow for the creation and deletion of temporary files.
12
- * **The `-shm` File:** All readers **must** have physical **Read/Write** access to this file to manage "read-marks," which prevent the writer from overwriting WAL frames currently being read.
13
- * **The `-wal` File:** Readers need Read access; the Writer needs Read/Write.
14
-
15
- -----
16
-
17
- ## 2\. The "Belt and Braces" Configuration
18
-
19
- This configuration prioritizes stability and **Conceptual Entropy Reduction (PHI-12)** by explicitly setting pragmas that prevent common race conditions.
20
-
21
- ```typescript
22
- import { Database } from "bun:sqlite";
23
-
24
- /**
25
- * Ctx Hardened SQLite Recipe
26
- * Implements: OH-082 (Slow Thinking), OH-041 (Optimal Simplicity)
27
- */
28
-
29
- const DB_PATH = "app_data.db";
30
-
31
- // 1. Initialize Connection
32
- const db = new Database(DB_PATH, { strict: true });
33
-
34
- // 2. Health Check & Config Sequence
35
- // CRITICAL: Set busy_timeout BEFORE any other pragmas
36
- db.run("PRAGMA busy_timeout = 5000;"); // Wait up to 5s for locks/recovery
37
-
38
- // 3. Stabilization Pragmas
39
- db.run("PRAGMA journal_mode = WAL;"); // Enable concurrency
40
- db.run("PRAGMA synchronous = NORMAL;"); // Safe for WAL, balances speed/integrity
41
- db.run("PRAGMA mmap_size = 0;"); // Disable mmap to prevent Mac I/O errors
42
- db.run("PRAGMA foreign_keys = ON;"); // Enforce relational integrity
43
-
44
- /**
45
- * Health Check: Validation of Operational State
46
- */
47
- function performHealthCheck() {
48
- const journalMode = db.query("PRAGMA journal_mode").get() as { journal_mode: string };
49
- const mmapSize = db.query("PRAGMA mmap_size").get() as { mmap_size: number };
50
-
51
- if (journalMode.journal_mode !== 'wal') throw new Error("HealthCheck Failed: WAL not active");
52
- if (mmapSize.mmap_size !== 0) throw new Error("HealthCheck Failed: mmap not disabled");
53
-
54
- // Simple Write/Read Test (The 'Proof' Artifact - OH-096)
55
- db.run("CREATE TABLE IF NOT EXISTS _health (id INTEGER PRIMARY KEY, ts TEXT)");
56
- db.run("INSERT INTO _health (ts) VALUES (datetime('now'))");
57
-
58
- return { status: "Healthy", substrate: "bun:sqlite", mode: journalMode.journal_mode };
59
- }
60
- ```
61
-
62
- -----
63
-
64
- ## 3\. Multi-Tenant Hardening Strategy
65
-
66
- To transform this into a multi-tenant system, we apply **Architectural Specialisation (PHI-14)**.
67
-
68
- | Layer | Implementation | Purpose |
69
- | :--- | :--- | :--- |
70
- | **Identity** | `tenant_id` column on every table. | Logical isolation of data. |
71
- | **Enforcement** | Use **Row Level Security (RLS)** patterns via Views. | Prevent "Leaky Abstractions" where one tenant sees another's data. |
72
- | **I/O Isolation** | `mmap_size = 0` | Prevents a crash in one process (Reader) from impacting the Writer via memory-map corruption. |
73
- | **Concurrency** | `SQLITE_BUSY_RECOVERY` handling. | Ensures readers wait for the Writer to finish WAL recovery before erroring out. |
74
-
75
- -----
76
-
77
- ## 4\. Operational Checklists (OPM-9)
78
-
79
- Before deploying, verify these "Lerts" (heightened alertness items):
80
-
81
- 1. **Integrity Check:** Run `PRAGMA integrity_check;` during maintenance windows to ensure no pages are corrupted.
82
- 2. **Writer-First Start:** Ensure the Writer process starts and initializes the WAL/SHM files *before* the Readers attempt to connect, minimizing `SQLITE_BUSY_RECOVERY` loops.
83
- 3. **Vacuum Strategy:** In WAL mode, use `PRAGMA auto_vacuum = INCREMENTAL;` to manage file size without locking the entire DB for long durations.
84
-
85
- Would you like me to generate a **Speculative Map** for how to automate these health checks into a Bun-based monitoring dashboard?
package/docs/headless-knowledge-management.md DELETED
@@ -1,79 +0,0 @@
1
- # Polyvis: The Case for Headless Knowledge Management
2
- **Status:** Draft / Strategic Artifact
3
- **Context:** Business Case & Operational Philosophy
4
- **Date:** December 2025
5
-
6
- ---
7
-
8
- ## 1. Executive Summary
9
- **Polyvis** is a self-organizing knowledge engine that transforms static file repositories into living, 3D intelligence graphs.
10
-
11
- Unlike traditional tools that force users to choose between a messy "digital attic" (SharePoint/Drive) or an expensive, opaque "Black Box" AI, Polyvis operates as a **Glass Box**. It runs entirely on local hardware, creates zero vendor lock-in, and turns raw documentation into "Cognitive Armor"—giving teams the structural leverage to win arguments and solve complex problems.
12
-
13
- ---
14
-
15
- ## 2. The Problem: The "Digital Attic"
16
- In most organizations, knowledge follows a tragic lifecycle:
17
- 1. **Creation:** Brilliance is captured in Briefs, Debriefs, and Playbooks.
18
- 2. **Storage:** These assets are dumped into rigid folder structures.
19
- 3. **Decay:** Without active curation, context has a half-life of two weeks. Links break, mental models fade, and the "Truth" becomes fragmented.
20
-
21
- When a crisis occurs 6 months later, the team is forced to "re-litigate" reality because they cannot see the timeline or the connections.
22
-
23
- ---
24
-
25
- ## 3. The Solution: Headless Knowledge Management
26
- Polyvis proposes a radical shift in architecture: **Separate the Data from the Intelligence.**
27
-
28
- ### A. The "Demilitarized Zone" (DMZ)
29
- We do not ask IT for complex AI procurement. We simply ask for a **Git Repository** of Markdown files.
30
- * **IT Department:** Happy because it is secure, standard, and audit-compliant.
31
- * **The User:** Happy because they own the raw data forever.
32
- * **The Mechanism:** This repo acts as a "Headless" database. It creates a "Cryogenic Freeze" for project context—it never decays.
33
-
34
- ### B. The Local Mind
35
- Polyvis acts as the disposable, high-speed engine that runs on the user's local machine. It connects to the "Headless" repo and re-hydrates the knowledge instantly.
36
-
37
- ---
38
-
39
- ## 4. The Mechanism: The "Forensic Darkroom"
40
- Polyvis treats document ingestion not as storage, but as a **Chemical Reaction**. When files are dropped into the engine, they are processed by a series of "Weavers" that expose hidden structures—much like developing film in a darkroom.
41
-
42
- ### The Triad of Context
43
- Every document is triangulated by three coordinates:
44
-
45
- 1. **Time (TimelineWeaver):**
46
- * *Function:* Links documents chronologically (e.g., Brief -> Debrief).
47
- * *Value:* Exposes the "Narrative Arc" of a project, revealing where intent drifted from reality.
48
-
49
- 2. **Space (StructureWeaver):**
50
- * *Function:* Anchors documents to their directory hierarchy.
51
- * *Value:* Provides "Gravity," ensuring related concepts cluster naturally together.
52
-
53
- 3. **Vibe (SemanticWeaver):**
54
- * *Function:* Uses local vector embeddings to link conceptually similar notes, even if they don't share keywords.
55
- * *Value:* Creates "Desire Lines"—shortcuts between ideas that humans forgot to link explicitly.
56
-
57
- ---
58
-
59
- ## 5. Operational Workflow: "Drop & Watch"
60
- The workflow is designed for maximum leverage with minimum friction.
61
-
62
- 1. **The Dump:** A user drops a new folder of documents (e.g., "Competitor Research") into the repo.
63
- 2. **The Reaction:** The Ingestion Daemon detects the new "Chemical Agent."
64
- 3. **The Synthesis:** The Weavers immediately stitch the new documents into the existing graph.
65
- * *Result:* The user does not search for the new files. They look for the **"Bridge Nodes"**—the specific points where the new information contradicts or reinforces existing knowledge.
66
- 4. **The Artifact:** The user commits their deductions back into the repo as an "Answer Artifact," creating a composite memory for the next person.
67
-
68
- ---
69
-
70
- ## 6. The Outcome: Asymmetric Insight
71
- The ultimate value of Polyvis is not "Search"; it is **Leverage**.
72
-
73
- By exposing the hidden structure of reality—the timelines, the gaps between promise and delivery, the unlinked mentions—Polyvis provides **Asymmetric Insight**.
74
-
75
- * **In Negotiation:** You know exactly what was said, when, and by whom.
76
- * **In Engineering:** You can trace the lineage of a bug from a vague requirement to a specific commit.
77
- * **In Strategy:** You can see which "Pillars" of your business are unsupported by documentation.
78
-
79
- It turns the user into the most informed person in the room. It is not just a tool for managing files; it is a machine for building the truth.