When the Wikantik engineering team concluded the database and storage profiling campaign in milestone 2.4.62, the system had successfully established its baseline runtime invariants: N+1 JDBC statement cascades were eliminated, the 79 GB Jena TDB2 disk leak was plugged, and in-place file overwrites were replaced with POSIX atomic renames. The roadmap then shifted toward horizontal scaling prerequisites and PgBouncer connection pooling.
However, running autonomous coding agents against Wikantik in daily production quickly exposed a different category of architectural pressure. While storage and database transactions were stable, multi-project agent sessions suffered from context window contamination, architecture documentation lacked native visual modeling, and human operator authoring remained burdened by manual markup formatting.
Between release 2.4.63 and release 2.5.3 (and the current 2.5.4 development stream), Wikantik executed a comprehensive architectural leap. Rather than treating a wiki as a static document store, the platform evolved into an active, visually expressive knowledge environment built for deep human-agent collaboration.
1. Storage Invariant Hardening and Lifecycle Integrity (v2.4.63)
Before introducing higher-level context features, the core persistence tier required closing subtle lifecycle leaks inherited from legacy JSPWiki foundations.
In prior versions, deleting a page through the web interface or administrative API removed the underlying markdown file, but frequently left orphaned relational artifacts behind. Extracted Knowledge Graph entity mentions, vector embeddings, and chunk metadata lingered in PostgreSQL tables until a manual administrative re-index was triggered. Worse, if a file deletion failed at the filesystem level, the application previously broadcast a PAGE_DELETED event regardless.
Milestone 2.4.63 established strict lifecycle invariants:
- Atomic Retirement: A genuine page deletion now formally retires the document's
canonical_id, drops all child chunks fromkg_content_chunks, cascades cleanly across vector embedding tables, and immediately evicts removed chunk identifiers from in-process BM25 and dense retrieval indexes. - Fail-Closed Deletion: If the underlying OS filesystem call fails to unlink a page, the operation throws an explicit exception; no deletion events are broadcast, and no database records are unlinked.
- Live Rename Synchronization: The structural graph index and Jena ontology listeners were rewired to subscribe directly to
WikiPageRenameEvent. Page renames now atomically re-key existing chunk rows, ensuring embeddings and semantic relationship triples survive document title changes without requiring re-computation. - Unified User Deletion: Self-service and administrative account removals were consolidated under a single
UserDeletionService, ensuring API tokens, group permissions, and persistent authentication cookies are revoked fail-closed before profiles are orphaned.
2. Project-Context Separation and Tiered Briefings (v2.4.64–v2.4.66 / ADR-0011)
As multiple autonomous agents began working across separate software repositories simultaneously, the global Context Briefing API (GET /api/briefing) encountered a severe signal-to-noise dilemma. When an agent queried for architectural guidance, vector similarity search routinely pulled sections across unrelated projects simply because they shared technical terminology like "database migration" or "connection pool." These out-of-scope sections flooded the agent's prompt budget, crowding out project-critical constraints.
To resolve this, Wikantik implemented Tiered Project-Context Separation (ADR-0011):
Briefing Assembly Pipeline (ADR-0011):
┌─────────────────────────────────────────────────────────────┐
│ 1. Tier 1: Cluster Members (Hub first, ranked by In-Degree) │
│ - Architectural contracts prioritized over runbooks │
├─────────────────────────────────────────────────────────────┤
│ 2. Tier 2: Cited Contracts (Discovered via Page Graph) │
│ - External pages cited by Tier 1 members │
├─────────────────────────────────────────────────────────────┤
│ 3. Elsewhere Pointers: Task hits outside Tiers 1 & 2 │
│ - Rendered as 1-line pointers (0 token body cost) │
└─────────────────────────────────────────────────────────────┘
Under this tiered model, context is partitioned dynamically:
- Tier 1 (Direct Cluster Members): The core pages declaring explicit membership in the requested project cluster. Rather than sorting by recent file modification timestamps—which previously caused an edited incident runbook to displace core architectural specifications—Tier 1 ranks pages by graph in-degree centrality. Hub documents and structural contracts appear first, while
type: runbookdocuments sort last. - Tier 2 (Cited Contracts): Pages outside the cluster that are explicitly linked by Tier 1 members. For instance, if the
rollerpublishing subsystem cites a central Wikantik authentication contract, that contract is automatically ingested into Tier 2 under## Contracts this project cites, without requiring manual multi-tagging. - Elsewhere Pointers: When running in
preferscope mode, vector search matches lying outside Tiers 1 and 2 are no longer dumped as full markdown text. Instead, they are rendered as compact one-line pointers under## Elsewhere in the wiki. The agent is notified of the document's existence, but zero token budget is wasted on irrelevant prose.
Note
Evaluation Harness (eval/briefing-scope): To guard against prompt drift, the team established a dedicated evaluation harness seeded from production agent traces. The harness computes automated separation and diversity scores, guaranteeing that cluster-scoped briefings maximize task relevance while enforcing strict context boundaries.
3. Visual Architecture: Sandboxed PlantUML and Native Mermaid (v2.5.0–v2.5.3)
Modern system design cannot rely on text alone; sequence interactions, component boundaries, and state machines require rigorous visual modeling. In releases 2.5.0 through 2.5.3, Wikantik introduced native client-side and server-side diagramming engines designed with enterprise sandbox boundaries.
Client-Side Mermaid with Interactive Page Graph Navigation (v2.5.0)
Markdown code blocks fenced with mermaid now render dynamically across the reader, editor previews, and transcluded embeds (![[embed]]). Unlike standard web renderers, Wikantik connects diagram elements directly to the wiki knowledge base: declaring click Node "/wiki/PageName" makes nodes interactive hyperlinks that are indexed by the Page Graph, count toward page backlinks, and validate against broken-link monitors. Rendering runs under securityLevel: antiscript, stripping embedded forms, scripts, and unsafe directives.
Server-Side Sandboxed PlantUML Engine (v2.5.1–v2.5.3)
For complex architectural modeling—including C4 system contexts, sequence interactions, activity swimlanes, @startsalt wireframes, and @startnwdiag network topologies—Wikantik introduced the dedicated wikantik-plantuml module. Executing arbitrary diagram generation on a production server introduces significant security and denial-of-service risks, which were mitigated through multi-layered isolation:
- Pure-Java Smetana Layout: Wikantik completely decouples PlantUML from native system binaries. The
GRAPHVIZ_DOTexecutable path is pointed to an unresolvable sink, forcing all graph generation through the pure-Java Smetana layout engine. No native C++ fork/exec processes can occur. - Zero I/O Security Sandbox: PlantUML executes within a strict security profile: local file access, URL fetching, environment variable reading, and remote
!includedirectives are blocked at the classloader boundary. The standard library is stripped exclusively to bundled C4 components. - SVG Allow-List Scrubbing: Generated SVG markup is sanitized through an allow-list scrubber that strips potential script injection vectors and prefixes element identifiers to prevent CSS collisions across document scopes.
- AOT-Accelerated Pre-Commit Gates: To prevent broken diagrams from entering the repository,
bin/check-plantuml.shscans corpus diagrams before commits. In milestone 2.5.3, this check was accelerated using JDK 25 Ahead-of-Time (AOT) cache training and the C1 compiler, reducing diagram validation latency from 0.60 seconds down to 0.35 seconds per document.
4. Frictionless Ingestion: Paste as Markdown (v2.5.4-SNAPSHOT)
The latest enhancement on the development branch tackles everyday documentation ergonomics. When engineers transfer architectural notes, meeting minutes, or legacy documentation into Wikantik from external tools—such as Google Docs, Microsoft Word, Confluence, GitHub Readmes, or browser windows—standard clipboards deliver messy, bloated HTML spans.
Integrated via commit a4f6595422, Wikantik’s web editor now features an intelligent, client-side Paste as Markdown engine powered by Turndown 7.2.4:
- Semantic HTML Conversion: Rich clipboard formatting is automatically parsed and translated into clean CommonMark (headers, bold/italic styles, ordered/unordered lists, blockquotes, and tabular structures).
- Intelligent URL Linking: Pasting a valid HTTP/HTTPS URL over selected text automatically converts the text into a clean markdown hyperlink (
[Selected Text](url)). - Contextual Bypass: The parser detects cursor position. If the user is typing inside a code fence or working on a legacy wiki-markup document, HTML conversion is bypassed entirely. Standard verbatim pasting remains accessible via
Mod-Shift-Vor the context menu's "Paste as plain text".
The Engineering Trajectory
Wikantik’s evolution illustrates a fundamental principle of AI-era software architecture: a reliable knowledge base must serve autonomous agents and human practitioners with equal precision. By hardening low-level storage invariants, partitioning agent briefing context via Page Graph citations, isolating diagram execution within sandboxed JVM boundaries, and removing editing friction, Wikantik 2.5 establishes a durable standard for agentic documentation systems.
References and Source Code Truth
- Wikantik Repository: ADR-0011 (Project Context is Derived from Citations) — Architectural Decision Record for tiered session briefings.
- Wikantik CHANGELOG.md (Releases 2.4.63 through 2.5.3) — Verified release notes and bugfix tracking.
- PlantUML Smetana: Pure Java Graphviz Layout Engine — Architecture of the native-free Java layout engine.
- Turndown: Extensible HTML to Markdown Converter — Technical specification for semantic DOM translation.
Comments