// SPDX-License-Identifier: CC-BY-SA-4.0
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>

= K9 Language Bindings
:author: Jonathan D.A. Jewell
:revdate: 2026-03-17
:toc: preamble
:icons: font

Official language bindings for parsing and rendering
https://github.com/hyperpolymath/standards/tree/main/k9-svc[K9 Self-Validating Component]
specifications. Each binding provides a typed AST, parser, and renderer for the
K9 format -- the security-tiered configuration language built on Nickel contracts.

== Feature Matrix

[cols="1,1,1,1,1,1"]
|===
| Feature | Deno (ReScript) | Rust | Gleam | Elixir | Haskell

| Parse `.k9` (YAML-like)
| Yes
| Yes
| Yes
| Yes
| Yes

| Parse `.k9.ncl` (Nickel)
| Yes
| Yes
| Yes
| Yes
| Yes

| Render to K9
| Yes
| Yes
| Yes
| Yes
| Yes

| Typed AST
| Yes
| Yes (serde)
| Yes
| Yes (structs)
| Yes (ADTs)

| Security levels
| Kennel/Yard/Hunt
| Kennel/Yard/Hunt
| Kennel/Yard/Hunt
| Kennel/Yard/Hunt
| Kennel/Yard/Hunt

| Contracts support
| Yes
| Yes
| Yes
| Yes
| Yes

| Round-trip fidelity
| Partial
| Partial
| Partial
| Partial
| YAML only

| Package registry
| https://jsr.io/@hyperpolymath/k9[JSR]
| https://crates.io/crates/k9-svc[crates.io]
| https://hex.pm/packages/k9_gleam[Hex.pm]
| https://hex.pm/packages/k9_ex[Hex.pm]
| https://hackage.haskell.org/package/k9[Hackage]

| License
| PMPL-1.0-or-later
| MPL-2.0
| MPL-2.0
| MPL-2.0
| MPL-2.0
|===

NOTE: Gleam, Elixir, Rust, and Haskell bindings use MPL-2.0 as a fallback because
their respective package registries (Hex.pm, crates.io, Hackage) require
OSI-approved licenses. PMPL-1.0-or-later is the preferred license.

== Quick Install

=== Deno (ReScript)

The primary binding, built with ReScript and published to JSR.

[source,sh]
----
deno add @hyperpolymath/k9
----

=== Rust

[source,sh]
----
cargo add k9-svc
----

=== Gleam

[source,sh]
----
gleam add k9_gleam
----

=== Elixir

Add to `mix.exs`:

[source,elixir]
----
defp deps do
  [{:k9_ex, "~> 0.1.0"}]
end
----

=== Haskell

[source,sh]
----
cabal install k9
----

Or add to your `.cabal` file:

[source,cabal]
----
build-depends: k9 >= 0.1 && < 0.2
----

== Shared API Surface

All bindings expose the same conceptual API:

`parse(input)`::
  Parse a K9 string (`.k9` or `.k9.ncl`) into a typed `Component` AST.

`render(component)`::
  Render a `Component` AST back to K9 surface syntax.

The `Component` type in every binding contains:

* *Pedigree* -- name, version, description, author, SPDX license
* *SecurityPolicy* -- trust level (Kennel/Yard/Hunt) and permission flags
  (network, filesystem write, subprocess)
* *Target* -- OS, edge mode, Podman requirement, memory constraint
* *Recipes* -- install, validate, deploy, migrate, and custom recipes
* *Validation* -- checksum, pedigree version, hunt authorisation flag
* *Contracts* -- contractile clauses (must/trust/dust/intend/k9)

== Security Levels

K9 uses a "leash" metaphor for trust tiers:

Kennel::
  Pure data. No code execution. Safe to open anywhere.
Yard::
  Controlled execution with Nickel contract evaluation. Limited permissions.
Hunt::
  Full execution with shell commands. Requires explicit signature/authorisation.

== Directory Layout

[source]
----
bindings/
  deno/         # @hyperpolymath/k9 — ReScript on Deno
  rust/         # k9-svc crate
  gleam/        # k9_gleam package
  elixir/       # k9_ex package
  haskell/      # k9 library
----

== Part of the K9 Ecosystem

These bindings are part of the
https://github.com/hyperpolymath/standards/tree/main/k9-svc[K9 Self-Validating Components]
suite within the `standards` monorepo. Related tools:

* link:../actions/validate/[`actions/validate`] -- GitHub Action for CI validation
* link:../pandoc/[`pandoc`] -- Pandoc reader, writer, and filter
* link:../editors/vscode/[`editors/vscode`] -- VS Code extension
* link:../SPEC.adoc[`SPEC.adoc`] -- K9 format specification
* link:../pedigree.ncl[`pedigree.ncl`] -- Nickel contract schema
