Polychro v1.0.0-beta1 — "Ketch"

Polychro v1.0.0-beta1 — "Ketch" ⚓ — Release Notes

⚓ A ketch is a sturdy two-masted vessel built for longer voyages — and beta1 is exactly
that: Polychro is confident enough to leave the alpha harbour. After alpha4 sharpened
diagnostic precision, "Ketch" makes JavaScript ruleset functions work reliably in the
native binary, fixes the functionsDir resolution bug that broke polyglot rules in
non-trivial setups, and ships the first complete Track 1 tutorial — verified against
the beta1 CLI itself. The linting engine is now stable enough for real integrations.

What is Polychro?

Polychro is a deterministic linting engine for spec-driven development. It validates
semi-structured specifications — YAML, JSON, Markdown, and OpenAPI — through composable
layers (well-formedness, schema-model, ruleset, and format-aware validation) in a single
embeddable pipeline with sub-second latency.

Built on Spectral's shoulders. Polychro adopts Spectral's given/then ruleset grammar —
the de facto standard for API governance rules — and extends it into a fully self-contained,
polyglot engine. Where Spectral requires Node.js and is narrowly focused on OpenAPI,
Polychro runs as a single JVM binary with no external runtime, supports custom rule
functions in JavaScript, Python, and Groovy, and lints YAML, JSON, Markdown, and OpenAPI
in the same pipeline.

💡 Polychro is designed to work alongside Ikanos —
validating capability specs before they reach the runtime — but it is fully standalone
and works with any YAML, JSON, or Markdown document.

This v1.0.0-beta1 release builds on v1.0.0-alpha4 ("Yawl") with a focus on
native-binary reliability and polyglot correctness: the GraalJS language loading
regression is fully resolved, functionsDir now resolves relative to the ruleset file
rather than the process working directory, and the Track 1 YAML tutorial is complete and
verified end-to-end. No breaking changes to the SPI or ruleset grammar.

✨ Highlights

🔧 Native CLI — GraalJS Language Loading Fixed (1812ba4)

The most impactful fix of beta1: JavaScript ruleset functions now execute correctly in the
GraalVM native binary on all platforms.

Root cause: the native profile was shading all dependencies into a single uber jar and
feeding it to native-image via -cp. On GraalVM JDK 21 (Truffle unchained), the Truffle
runtime declares a ForceOnModulePath attribute that requires language jars (GraalJS +
Truffle) on the module path. An uber jar has no module descriptor, so the JS language could
not register — resulting in "No language and polyglot implementation was found on the
module-path" at runtime.

Fix (per GraalVM's official guidance — uber jars are not supported for native image with
embedded languages):

• The maven-shade-plugin is removed from the native profile; native-maven-plugin
  (extensions=true) now feeds native-image the full runtime classpath as individual
  jars — native-image auto-upgrades the polyglot modules to the module path so GraalJS
  registers correctly
• The invalid --language:js build flag and explicit -H:ReflectionConfigurationFiles /
  -H:ResourceConfigurationFiles args are dropped — each jar's META-INF/native-image
  configs are now read automatically
• The transitive Apache Groovy dependency (pulled via polychro-capability →
  ikanos-engine, unused by the CLI) is excluded — Groovy 4.x invokedynamic
SwitchPoints reach MethodHandleNatives.setCallSiteTargetNormal, a method deleted by
  GraalVM SVM, which otherwise fails the image build
  (e55d967,
  31fbe62)

Validated on macOS ARM64 (Oracle GraalVM 21.0.11): the native binary executes JS ruleset
functions and emits identical JSON diagnostics to the JVM jar.

🗂️ Polyglot functionsDir Resolution Fixed (#44)

functionsDir in .polychro.yml now resolves relative to the ruleset file, not
relative to the process working directory — so running polychro lint from any directory
produces consistent results (9829e23).

JavaScript function files referenced in rulesets are now discovered and loaded correctly
regardless of where the CLI is invoked from.

📖 Track 1 YAML Tutorial — Complete & Verified (#49)

The first complete Polychro tutorial track ships with beta1, built around the Modern
Maritime Registry API and covering 7 progressive linting steps:

• Step 1–7 YAML examples (examples/tutorial/track-1-yaml/) — runnable OpenAPI
  documents that introduce one defect per step, progressively exercising well-formedness,
  schema validation, built-in ruleset rules, and polyglot JS functions
  (4bafc1d,
  dc15ce7)
• Verified against beta1 CLI — all 7 examples were run against the freshly built
  polychro 1.0.0-beta1 binary; EXPECTED-OUTPUT.md contains the real per-step output,
  not hypotheses (a43a956)
• tuto_writer agent — a new .claude/agents/tuto_writer.agent.md agent drives
  tutorial authoring, ensuring examples stay aligned with the real engine behaviour
• LIMITATIONS.md — two known limitations discovered during verification are
  documented: a non-string-key false positive on quoted HTTP status codes (#5) and
  .polychro.yml schema config not being consumed in Step 4 (#6)

🌙 CI / Quality Automation

• Slack notifications on nightly failures — the quality-gate now pages the team when a
  nightly run fails (d1ba985)
• Nightly quality-gate workflow fixed (1936426)
• macOS runner pinned to macOS 15 to work around a GitHub Actions latest → 16 transition
  issue (16b25de)

🤝 polychro-ruleset-polyglot — Production Hardening

• PolyglotFunctionLoader and PolyglotRuleFunction hardened with improved JS doc
  handling (e83d949)
• New tests: FunctionsDirResolutionTest, PolyglotFunctionLoaderTest,
  PolyglotRuleFunctionTest — unit coverage for the full polyglot function lifecycle

📚 Documentation

• README restructured around reader personas for faster onboarding
  (dd71a5d)
• Links tightened and converted to relative Shipyard docs paths
  (bf2b4c0)
• README links updated to point to shipyard.naftiko.io alpha4 docs
  (5a1debc)
• VS Code problems in polychro resolved (611fedb)

⚠️ Known Issues & Limitations

• Non-YAML source ranges — built-in and polyglot ruleset diagnostics carry precise
  ranges for YAML documents; JSON, Markdown, and HTML still report SourceMap.NONE
  pending follow-up (#34–#37)
• Tutorial known limitations — two edge cases found during Track 1 verification:
  non-string-key false positive on quoted HTTP status codes (LIMITATIONS #5), and
  .polychro.yml schema config not consumed when the schema is declared in Step 4
  (LIMITATIONS #6); documented, fix planned
• CLI pre-built binary installation — running the binary directly is not
  straightforward on macOS (Gatekeeper quarantine: xattr -dr com.apple.quarantine) or
  Windows (SmartScreen warning, unsigned binary). Workaround: run via java -jar polychro.jar
• polychro-rulesets JaCoCo coverage — pre-existing gap on main; coverage gate not
  yet enforced for this module
• Checkov — requires a local Checkov installation; not bundled in the binary
• CLI pre-built binaries available for macOS ARM64, Linux AMD64, Linux ARM64, and
  Windows AMD64

🔢 By the Numbers

• 21 commits merged since v1.0.0-alpha4
• 30 files changed, +1,324 / −270 lines
• 4 contributors

🙏 Contributors

Huge thanks to the team for shipping this release:

• @jeremnaf — GraalJS native binary fix (root cause analysis & full fix), macOS CI runner, Groovy exclusion, release coordination
• @eskenazit — Track 1 YAML tutorial (scaffold, maritime realignment, beta1 verification), functionsDir resolution fix (#44), beta1 version bump
• @farah-t-trigui — Slack nightly notifications, nightly quality-gate fix
• @jlouvel — README restructuring, documentation, VS Code fixes, engine support

Full Changelog: v1.0.0-alpha4...v1.0.0-beta1