Skip to content

v1.0.0-alpha3 — Trimaran

Pre-release
Pre-release

Choose a tag to compare

View all tags
@github-actions github-actions released this 27 May 08:54
· 47 commits to main since this release
v1.0.0-alpha3
46daadf

Naftiko Framework v1.0.0-alpha3 — "Trimaran" ⛵ — Release Notes

⛵ The third Alpha trims the sails! This release brings a complete rename to Ikanos, a unified import mechanism, named entities as keyed maps, a reverse-tunnel engine, thread-safety hardening, and expanded JaCoCo coverage enforcement — moving the framework toward a production-ready, polyglot integration engine.

What is the Naftiko Framework?

The Naftiko Framework — now branded Ikanos — is an open-source Java runtime that lets you declare, compose, and expose API capabilities — from simple HTTP proxies to AI-ready MCP tools — using a declarative, specification-driven approach.

This v1.0.0-alpha3 release builds on v1.0.0-alpha2 with a focus on structural consistency, extensibility, security hardening, and developer ergonomics. The package namespace migrates from io.naftiko to io.ikanos, the codebase is split into four focused Maven modules, and the specification gains first-class support for named entities, import references, and reverse tunnels.

🌐 Ecosystem

Polychro — Spec Linting for Ikanos Capabilities

Polychro is the companion spec linting engine for the Ikanos ecosystem. It validates Ikanos capability files against rulesets declared in YAML, surfacing diagnostics as SARIF, JSON, or LLM-native output — directly inside your editor, CI pipeline, or AI agent.

Starting with this alpha cycle, Polychro ships alongside Ikanos as a first-class peer project. See the [Polychro ] release notes for the full changelog.

✨ Highlights

🤖 Agent & Contributor Experience

  • PR Review Skill v2 — batch line lookup, pick-before-line resolution, no-ghost-review rule, multi-OS support, pre-submission guard, temp-file safety rules
  • Part B added to pr-review skill — automated fix-PR-comments workflow with reply & resolve step
  • Parallel agent workflows documented — git worktree usage, handoff naming convention, Mode B receiving-agent workflow
  • AGENTS.md updated: field-type migration rule, unit/integration test boundary clarification, issue-proposal-before-work requirement, reusable PowerShell scripts
  • Context compaction rule: re-read active skill's SKILL.md after compaction

🏷️ Ikanos Rename & Package Migration

The framework has been formally rebranded from Naftiko to Ikanos:

  • Package namespace migrated: io.naftiko → io.ikanos across all modules
  • Specification renamed to Ikanos Specification; CLI artifact becomes ikanos.jar
  • Tooling (VS Code extension, GitHub Actions, wiki, badges) updated to reflect the new identity
  • Internal naming aligned: Crafter (IDE), Warden (Backstage), Shipyard (portal)

📦 Codebase Modularization

A monolithic source tree has been refactored into four focused Maven modules:

  • ikanos-spec — SPI contracts and POJO model
  • ikanos-engine — orchestration and runtime
  • ikanos-cli — Picocli CLI and serve runtime
  • ikanos-docs — wiki and documentation sources

Each module has independent JaCoCo enforcement, explicit Restlet dependencies, and isolated test coverage.

🔑 Named Entities as Keyed Maps

Named objects are now first-class citizens throughout the specification:

  • outputParameters, aggregates, and flows use a keyed-map shape — keys serve as stable identifiers
  • label renamed to display for semantic clarity
  • aggregate.functions renamed to aggregate.flows for extensibility and alignment with the flow model
  • tags added to capability sub-entities (operations, tools, flows)
  • unevaluatedProperties moved to root level; schema branches made mutually exclusive (oneOf)
  • Spectral rules, fixtures, and deserializers updated to reflect the new shape (#328, #495)

🔗 Unified Import Mechanism

Capabilities can now be composed from external specs via a first-class import mechanism:

  • Phase 1 (Spec & Schema) — import section in capability YAML with typed references
  • Phase 2 (Engine Resolver) — runtime resolution of import refs at startup
  • Phase 3 (Validation & Tutorial) — Spectral validation rules, v8r exclusions, and end-to-end tutorial step
  • ExposesImportStrategy.deepCopy uses a concrete runtime class for safe serialization
  • Import test fixture helper files excluded from MegaLinter schema validation (#505, #506)

🚇 Reverse-Tunnel Engine (OpenZiti)

Private APIs hosted behind firewalls can now be consumed via a sidecar tunnel pattern:

  • New reverse-tunnel SPI in ikanos-engine with a dedicated TunnelAdapter interface
  • OpenZiti implementation — zero-trust network access via the OpenZiti SDK
  • Jetty wiring for the tunnel server endpoint
  • Reverse-tunnel schema, spec POJOs, Spectral linter rules, and worked examples
  • Reverse Tunnel guide added to the wiki (private APIs, sidecar pattern) (#513, #515)

🔒 Thread-Safety Hardening (S3077)

Shared mutable state has been systematically eliminated across spec POJOs and the engine:

  • Credential fields migrated to AtomicReference with defensive copies (auth specs)
  • Engine volatile fields wrapped in AtomicReference snapshots
  • OperationStepExecutor race condition resolved (#320)
  • Failing meta-tests written first to prove each concurrency bug before fixing

🧩 Embedded Library Mode & Step Handler Registry

The engine can now be embedded as a library with a pluggable step-handler registry:

  • StepHandlerRegistry — runtime registry for custom step implementations
  • NaftikoEngine merged into Capability to reduce surface and simplify embedding
  • ScriptStepExecutor instantiation deferred to avoid eager GraalVM class loading
  • Embedding test fixture added and schema-conformant

🔭 Observability Improvements

Building on the alpha2 OTel stack:

  • OpenTelemetry is now disableable with near-zero overhead when not needed
  • TelemetryBootstrap singleton reset in integration test teardown (test isolation)
  • OTel null-safety and Restlet bridge helpers extracted into reusable utilities
  • Observability telemetry hardened; CLI runtime observability dependencies restored
  • localhost:4317 OTLP default disabled when no control adapter is configured

📐 Specification & Schema Refinements

  • Schema oneOf branches made mutually exclusive for capability documents
  • Spectral aggregate-semantics-consistency and aggregate-function-unique rules updated for keyed-map shape
  • Spectral fixtures migrated to keyed-map format; v8r exclusions broadened for import helpers
  • Bearer auth always 401 when token resolved from file-based binding — fixed (#482)

🔧 Engine Fixes

  • Bearer auth always 401 when token resolved from file-based binding (#482) ✅
  • putIfAbsent forced to none even when env var was set — now checks env var first ✅
  • localhost patched to 0.0.0.0 for serve runtime binding ✅
  • Aggregate keyed-map deserialization using namespace key ✅
  • Duplicate Restlet dependency removed; duplicate SLF4J binding eliminated ✅
  • CLI formatDuration and averageDurationMs use Locale.ROOT for locale-safe formatting ✅
  • Shutdown polling I/O failure propagated correctly on unexpected shutdown ✅
  • GraalVM reflect config dependencies added for native CLI image ✅

📦 CI/CD & Quality

  • JaCoCo 100% enforcement added at current baseline for all modules (#446)
  • Sonar Quality Gate reached zero bugs — all S3077 and critical issues resolved (#216) ✅
  • ikanos-coverage module introduced (CI-only, no central publishing, no GPG signing)
  • CLI GitHub Action renamed from Naftiko to Ikanos
  • Tutorial fixture corrections: label → display, functions → flows, keyed-map outputParameters
  • Version bump automation: post-release version sync across pom.xml, YAML fixtures, schema, and VS Code package.json
  • MegaLinter v8r exclusion broadened to cover all import test fixture helpers
  • Javadoc package-level descriptions added for all packages

⚠️ Known Issues & Limitations

  • CLI pre-built binary installation — running the CLI binary directly is not straightforward on macOS (Gatekeeper quarantine requires manual xattr -dr com.apple.quarantine or system approval) and on Windows (SmartScreen warning, unsigned binary). Workaround: run via java -jar ikanos.jar from the JAR instead (#281)
  • CLI pre-built binaries — available for macOS ARM64, Linux AMD64, Linux ARM64, and Windows AMD64

🔢 By the Numbers

  • ~187 commits merged since v1.0.0-alpha2
  • 759 files changed, +34,139 / −40,788 lines
  • 4 contributors

🙏 Contributors

Huge thanks to the team for shipping this release:

  • @eskenazit — keyed-map spec, unified import mechanism, schema refinements, Spectral rules, PR review skill v2, AGENTS.md governance
  • @farah-t-trigui — CI/CD improvements, JaCoCo enforcement, tutorial corrections, version sync automation
  • @jeremnaf — CLI coverage, ikanos-cli modularization, native build fixes, step handler registry
  • @jlouvel — Ikanos rename, modularization, reverse-tunnel engine, embedded library mode, thread-safety hardening, observability improvements, engine fixes

Full Changelog: v1.0.0-alpha2...v1.0.0-alpha3

Assets 6
Loading