{"id":50434041,"url":"https://github.com/gazolla/mk8","last_synced_at":"2026-05-31T16:01:47.830Z","repository":{"id":361468898,"uuid":"1254558520","full_name":"gazolla/MK8","owner":"gazolla","description":"A modular, asynchronous, and event-driven MicroKernel system implemented in Java  and Jbang.","archived":false,"fork":false,"pushed_at":"2026-05-30T19:07:02.000Z","size":98,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-30T20:17:44.753Z","etag":null,"topics":["java","jbang","microkernel"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gazolla.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-30T18:08:41.000Z","updated_at":"2026-05-30T19:07:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gazolla/MK8","commit_stats":null,"previous_names":["gazolla/mk8"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/gazolla/MK8","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gazolla%2FMK8","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gazolla%2FMK8/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gazolla%2FMK8/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gazolla%2FMK8/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gazolla","download_url":"https://codeload.github.com/gazolla/MK8/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gazolla%2FMK8/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33737692,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","jbang","microkernel"],"created_at":"2026-05-31T16:01:47.018Z","updated_at":"2026-05-31T16:01:47.799Z","avatar_url":"https://github.com/gazolla.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MK8 MicroKernel\n\nA modular, asynchronous, and event-driven MicroKernel system implemented in Java 21+. It enables independent processes (plugins) to discover and call each other's capabilities over Unix Domain Sockets (UDS) using JSON event frames, eliminating compile-time or static network dependencies.\n\nFor a conceptual deep dive into the system's core design patterns — such as capability bidding auctions, idempotency caching, Single-Flight request collapsing, lifecycles, and distributed tracing — consult the **[System Concepts Guide](docs/CONCEPTS.md)**. To explore the concrete code layout, class descriptions, and core API interfaces (`EventInterceptor`, `KernelBus`, `PluginRuntime`), review the **[System Architecture Reference](docs/ARCHITECTURE.md)**.\n\n---\n\n## 1. Project Structure\n\n* 📁 **MK8 (Project Root)**\n  * 📄 **[Start.java](Start.java)** — Bootrunner: spawns Kernel and SummaryAgent in the background, streams DemoRunner in the foreground, auto-generates `logs/start.log` via `TeeOutputStream`, and tears down all processes on exit.\n  * 📄 **[README.md](README.md)** — Main entry point (Setup, Quick Start, and documentation index).\n  * 📁 **`logs/`** — Auto-created on first run. Contains `start.log` (full run transcript), `kernel.log`, `summary-agent.log`, and `word-count.log`.\n  * 📁 **`kernel/`** *(MicroKernel Core Infrastructure)*\n    * 📄 **[Kernel.java](kernel/Kernel.java)** — UDS server, routing tables, interceptor chain wiring, and top-level records (`CatalogEntry`, `PrefixRoute`, `Connection`). Also defines the `EventInterceptor`, `KernelBus`, and `PluginRuntime` interfaces. *(See **[Core Kernel Architecture](docs/KERNEL.md)**)*\n    * 📄 **[KernelEvent.java](kernel/KernelEvent.java)** — JSON event envelope, 4-byte length-prefixed frame protocol, Jackson factory methods, and timestamp-prefixing logging. *(See **[KernelEvent Taxonomy Reference](docs/EVENTS.md)**)*\n    * 📄 **[PluginConfig.java](kernel/PluginConfig.java)** — Typed accessors for `plugin.json` (id, lifecycle, capabilities, launch command, llm, agent, thinking blocks).\n    * 📄 **[PluginBase.java](kernel/PluginBase.java)** — Plugin bootstrap: UDS connect, `plugin.register` handshake, virtual-thread dispatcher, and auto-bidding. *(See **[PluginBase Reference](docs/PLUGIN_BASE.md)**)*\n    * 📄 **[PluginManager.java](kernel/PluginManager.java)** — Single source of truth for plugins: directory scan, catalog indexing, on-demand process spawn, idle-kill sweep. Implements `PluginRuntime`. *(See **[PluginManager Guide](docs/PLUGIN_MANAGER.md)**)*\n    * 📄 **[CapabilityInterceptor.java](kernel/CapabilityInterceptor.java)** — Live capability registry, bidding auction engine, built-in capability dispatcher. Depends only on `PluginRuntime` — zero reference to `PluginManager`. *(See **[CapabilityInterceptor Guide](docs/CAPABILITY_INTERCEPTOR.md)**)*\n    * 📄 **[IdempotencyInterceptor.java](kernel/IdempotencyInterceptor.java)** — Single-Flight request collapsing and sliding-window result cache. *(See **[Idempotency \u0026 Collapsing Guide](docs/IDEMPOTENCY.md)**)*\n  * 📁 **`system/`** *(Persistent Orchestrators)*\n    * 📁 **`demo-runner/`** — Verification client: fires concurrent and sequential requests, validates collapsing and cache hits. *(See **[Pipeline Verification Demo](docs/VERIFICATION_DEMO.md)**)*\n    * 📁 **`summary-agent/`** — Persistent orchestrator that delegates to WordCountTool and returns formatted analysis reports.\n  * 📁 **`tools/`** *(On-Demand Workers)*\n    * 📁 **`word-count/`** — On-demand tool: word, sentence, and unique-word counting. *(See **[Creating a Plugin from Scratch](docs/CREATE_PLUGIN.md)**)*\n\n---\n\n## 2. Quick Start: Run the Pipeline in One Command\n\n### Prerequisites\n* **JDK 21+**\n* **JBang** on your PATH\n\n### Run Command\n```bash\njbang Start.java\n```\n\n### Expected Console Output\n```text\n=======================================================\n          MK8 MicroKernel — Boot Runner                \n=======================================================\n\n[BOOT] Starting Kernel.java in the background...\n[BOOT] Waiting for Kernel UDS socket to bind..... Connected! (Socket verified)\n\n[BOOT] Starting SummaryAgent.java in the background...\n[BOOT] Executing DemoRunner.java in the foreground...\n\n╔══════════════════════════════════════════════════════╗\n║    MK8 Kernel-Extendido — Idempotency \u0026 Collapsing    ║\n║  3 plugins: DemoRunner → SummaryAgent → WordCount    ║\n╚══════════════════════════════════════════════════════╝\n\n[DEMO] === STARTING IDEMPOTENCY \u0026 COLLAPSING TEST ===\n\n[DEMO] → Sent concurrent request #1 corrId=haiku-collapsed-id\n[DEMO] → Sent concurrent request #2 (duplicate) corrId=haiku-collapsed-id\n[DEMO] Both requests in-flight. Waiting for collapsing...\n\n[DEMO] 🟢 Plugin spawned: word-count pid=32221\n┌─ Result received (latch=3) corrId=haiku-collapsed-id ──\n│ 📄 Text Analysis Report\n│ ─────────────────────────────\n│ Words:            13\n│ Sentences:        1\n│ Unique words:     12  (rich vocabulary)\n│ Avg words/sentence: 13,0\n│ ─────────────────────────────\n│ Top words: pond(×2) the(×1) into(×1) a(×1) silent(×1)\n└──────────────────────────────────────────────────────\n\n┌─ Result received (latch=2) corrId=haiku-collapsed-id ──\n│ 📄 Text Analysis Report\n│ ─────────────────────────────\n│ Words:            13\n│ Sentences:        1\n│ Unique words:     12  (rich vocabulary)\n│ Avg words/sentence: 13,0\n│ ─────────────────────────────\n│ Top words: pond(×2) the(×1) into(×1) a(×1) silent(×1)\n└──────────────────────────────────────────────────────\n\n[DEMO] === RUNNING SEQUENTIAL CACHE HIT TEST ===\n[DEMO] Sending duplicate request #3 sequentially (corrId=haiku-collapsed-id)...\n[DEMO] → Sent sequential request #3 in 0ms\n┌─ Result received (latch=1) corrId=haiku-collapsed-id ──\n│ 📄 Text Analysis Report\n│ ─────────────────────────────\n│ Words:            13\n│ Sentences:        1\n│ Unique words:     12  (rich vocabulary)\n│ Avg words/sentence: 13,0\n│ ─────────────────────────────\n│ Top words: pond(×2) the(×1) into(×1) a(×1) silent(×1)\n└──────────────────────────────────────────────────────\n\n\n════════════════════════════════════════════════════════════════════════════════\n                   🔬 PIPELINE PERFORMANCE \u0026 METRICS SUMMARY\n════════════════════════════════════════════════════════════════════════════════\n\n📊 Text Computational Metrics Breakdown:\n   • Input text: \"An old silent pond a frog jumps into the pond splash silence again.\"\n   • Total words: 13 (tokens separated by spaces)\n   • Sentences:   1 (single trailing punctuation block)\n   • Unique words: 12 (the word \"pond\" is repeated twice, demonstrating duplicate deduplication)\n\n🚀 Kernel-Level Concurrency Optimizations Verified:\n   • Request Collapsing (Single-Flight):\n     Request #1 and Request #2 were dispatched concurrently.\n     The Kernel's IdempotencyInterceptor intercepted the duplicate in-flight\n     correlation ID and collapsed them, routing only ONE invocation to the SummaryAgent.\n     Both callers received their outcomes, but downstream work was executed only ONCE.\n     (Confirmed: only one analysis request is logged in 'summary-agent.log').\n\n   • Sliding-Window Idempotency Caching:\n     Request #3 was dispatched sequentially.\n     The Kernel bypassed the active plugins completely, serving the response\n     directly from its high-performance memory cache in under 1 millisecond.\n     (Confirmed: zero requests were dispatched to SummaryAgent / WordCountTool).\n\n════════════════════════════════════════════════════════════════════════════════\n✅ All 3 analyses complete! Idempotency \u0026 Collapsing successfully validated.\n════════════════════════════════════════════════════════════════════════════════\n\n\n[BOOT] DemoRunner finished with exit code: 0\n\n[BOOT] Cleaning up background processes...\n[BOOT] Terminated background process PID=32186\n[BOOT] Terminated background process PID=32197\n[BOOT] Cleaned up socket file.\n[BOOT] Shutdown complete.\n```\n\n---\n\n## 3. The Text Analysis Verification Example\n\nFor a detailed explanation of the text analysis example (word, sentence, and vocabulary counting), including the component breakdown, class roles, publisher/consumer event chain tables, and sequence flowcharts, please refer to the dedicated **[Pipeline Verification Demo Guide](docs/VERIFICATION_DEMO.md)**.\n\n---\n\n## 4. Manual Sequential Execution (For Process Inspection)\n\nIf you prefer to inspect individual process streams and logs in real time, execute the components sequentially in three separate terminal windows:\n\n### Step 1: Start the Core Kernel UDS Server\n```bash\ncd kernel\njbang Kernel.java\n```\n\n### Step 2: Start the Summary Agent\n```bash\ncd system/summary-agent\njbang SummaryAgent.java\n```\n\n### Step 3: Execute the Demo Runner\n```bash\ncd system/demo-runner\njbang DemoRunner.java\n```\n\n---\n\n## 5. Documentation Index\n\n* **[Core Kernel Architecture](docs/KERNEL.md):** UDS channel communications, length-prefixed binary framing, virtual-thread topology, and the interceptor chain pipeline.\n* **[System Concepts](docs/CONCEPTS.md):** Capability auctions, idempotency caching, Single-Flight request collapsing, persistent/on-demand lifecycles, and distributed tracing.\n* **[System Architecture \u0026 Class Reference](docs/ARCHITECTURE.md):** Class layout, interface specs (`EventInterceptor`, `KernelBus`, `PluginRuntime`), and method signatures.\n* **[KernelEvent Taxonomy Reference](docs/EVENTS.md):** Complete event catalog: `capability.*`, `system.plugin.*`, `message.*`, built-in capability names.\n* **[PluginManager Guide](docs/PLUGIN_MANAGER.md):** Catalog scan, `CatalogEntry` record, on-demand process spawn, idle-kill sweep, and the `PluginRuntime` interface.\n* **[CapabilityInterceptor Guide](docs/CAPABILITY_INTERCEPTOR.md):** Live registry, bidding auction engine, `handleInvoke` flow, and built-in handler dispatch map.\n* **[Idempotency \u0026 Collapsing Guide](docs/IDEMPOTENCY.md):** Single-Flight collapsing implementation, sliding-window result cache, and memory-leak guards.\n* **[PluginBase Reference](docs/PLUGIN_BASE.md):** Plugin bootstrap, `run()`, `publish()`, auto-bidding (`handleBidAuto`), and virtual-thread dispatch lifecycle.\n* **[Pipeline Verification Demo Guide](docs/VERIFICATION_DEMO.md):** Component roles, publisher/consumer event chain table, and sequence flowchart for the text analysis pipeline.\n* **[Creating a Plugin from Scratch](docs/CREATE_PLUGIN.md):** Step-by-step guide: `plugin.json`, instance pattern (`new Plugin().start()`), triggerEvent wiring, and pipeline integration.\n* **[Plugin Configuration Schemas](docs/PLUGIN_SCHEMAS.md):** Full `plugin.json` field reference for `system`, `tool`, and `agent` types; launch block; boot-order tiers.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgazolla%2Fmk8","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgazolla%2Fmk8","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgazolla%2Fmk8/lists"}