Living Document Notice
Published 2026-09-21. The evolving architecture, revisions, and connected notes for this dispatch live in the Stax Digital Garden.
The Open-Core Line
Summary
Open-core software architectures require strict structural boundaries between local computational libraries and centralized control planes. When commercial features are mixed directly into parsing libraries, open-source consumers face licensing ambiguities, unexpected network telemetry, and vendor lock-in.
Bosun draws an explicit architectural line. All parsing engines, syntax grammars, and local search routines remain permissively licensed open-source software under the MIT license. The commercial tier, centered on the Harbormaster KPP protocol fleet control plane, operates exclusively as an external orchestration service for multi-node deployment, telemetry aggregation, and automated provisioning.
Demarcation of System Responsibilities
The primary risk in open-core software is functional contamination. In poorly partitioned codebases, local parsing routines import proprietary remote client libraries, creating non-optional runtime dependencies on commercial endpoints.
To prevent this entanglement, Bosun establishes an absolute separation between the client parser engine and the fleet coordination plane.
+-------------------------------------------------------------+
| Permissive Open-Source Core |
| (MIT / Apache-2.0) |
| |
| +--------------------+ +--------------------+ |
| | Tree-sitter Parser | <---------> | Local Query Engine | |
| +--------------------+ +--------------------+ |
| | | |
| v v |
| +-------------------------------------------------------+ |
| | In-Memory Abstract Syntax Tree | |
| +-------------------------------------------------------+ |
+-------------------------------------------------------------+
|
POSIX Sockets / IPC
|
+-------------------------------------------------------------+
| Commercial Harbormaster Plane |
| (Proprietary) |
| |
| +--------------------+ +--------------------+ |
| | Fleet Provisioner | | Tenant Auth & ACL | |
| +--------------------+ +--------------------+ |
| | | |
| v v |
| +-------------------------------------------------------+ |
| | Multi-Node Telemetry & Cluster Quotas | |
| +-------------------------------------------------------+ |
+-------------------------------------------------------------+
The core engine contains no networking code, no analytics SDKs, and no phone-home mechanisms. It consumes plain-text buffers from standard file descriptors and emits structured AST nodes into local memory arenas. Harbormaster connects to the core engine strictly through external POSIX pipes or network RPCs, functioning as an external supervisor rather than an embedded dependency.
Structural Comparison of Architectural Tiers
The operational boundaries between the local parsing layer and the remote management plane are codified across four technical dimensions.
| Dimension | Open-Source Core Engine | Harbormaster Control Plane |
|---|---|---|
| Licensing Model | MIT License | Commercial Proprietary |
| Network Capabilities | Zero network syscalls compiled into binary | TLS 1.3 HTTP/gRPC cluster orchestration |
| Runtime Environment | Embedded local process / WebAssembly | Multi-tenant Linux daemon / Container |
| Data Access | Direct POSIX read/write on local vault | Metadata metrics and aggregate health states |
| Build Artifact | Standalone static binary (bosun-core) | Orchestration daemon (harbormasterd) |
Because the core engine is strictly decoupled from network infrastructure, users can compile and execute the complete parsing suite in air-gapped environments without license validation checks.
Decoupled Parser Interface Contract
The open-source core defines abstract traits for document processing. The local runtime satisfies these traits using Tree-sitter grammars. Harbormaster consumes exported metrics over structured byte streams without altering the parser execution path.
pub trait DocumentParser {
fn parse_buffer(&self, input: &[u8]) -> Result<SyntaxTree, ParseError>;
fn extract_frontmatter(&self, tree: &SyntaxTree) -> Result<FrontmatterMap, ParseError>;
fn resolve_wikilinks(&self, tree: &SyntaxTree) -> Vec<LinkReference>;
}
pub struct CoreTreeSitterParser {
language: tree_sitter::Language,
}
impl DocumentParser for CoreTreeSitterParser {
fn parse_buffer(&self, input: &[u8]) -> Result<SyntaxTree, ParseError> {
let mut parser = tree_sitter::Parser::new();
parser.set_language(self.language)?;
let tree = parser.parse(input, None)
.ok_or(ParseError::TreeGenerationFailed)?;
Ok(SyntaxTree { inner: tree })
}
fn extract_frontmatter(&self, tree: &SyntaxTree) -> Result<FrontmatterMap, ParseError> {
parse_yaml_cst_node(&tree.inner)
}
fn resolve_wikilinks(&self, tree: &SyntaxTree) -> Vec<LinkReference> {
collect_link_nodes(&tree.inner)
}
}Notice that CoreTreeSitterParser implements no remote synchronization primitives. If a deployment integrates with Harbormaster, an external daemon subscribes to file change events and invokes the parser through standard library calls.
Licensing Verification Invariant
The structural invariant governing the codebase mandates that the bosun-core crate must never include dependencies outside permissive licenses (MIT, Apache-2.0, or BSD-3-Clause), nor compile network socket symbols in release profiles.
Validate compliance in CI environments by executing cargo-deny:
cargo deny check licenses && nm target/release/libbosun_core.a | grep -E "(connect|socket|getaddrinfo)" || true- Directus Target: bosunpkm-blog
- Garden Source Reference: MOC - Bosun PKM Engine, MOC - Bosun PKM Tools, MOC - Harbormaster Protocol