// SPDX-License-Identifier: CC-BY-SA-4.0
// (PMPL-1.0-or-later preferred; MPL-2.0 required for Hex.pm)
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>

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

K9 (Self-Validating Components) parser and renderer for
https://gleam.run[Gleam]. Parse and render K9 component specifications with
full type safety on the BEAM or JavaScript targets.

== What It Does

`k9_gleam` provides a typed AST, parser, and renderer for the K9 format --
a security-tiered configuration language built on Nickel contracts. K9 files
embed pedigree metadata, security levels, build recipes, and validation
checksums directly in the document.

The library handles both K9 syntax variants:

* `.k9` -- YAML-like declarative syntax (Kennel level)
* `.k9.ncl` -- Nickel-based programmable syntax (Yard/Hunt level)

== Installation

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

This adds `k9_gleam` to your `gleam.toml` dependencies from
https://hex.pm/packages/k9_gleam[Hex.pm].

== Usage

[source,gleam]
----
import k9_gleam
import k9_gleam/parser
import k9_gleam/renderer

pub fn main() {
  let input =
    "pedigree:\n  name: hello-k9\n  version: 1.0.0\n  description: A greeting\n\nsecurity:\n  level: kennel"

  // Parse a K9 string into a Component AST
  let assert Ok(component) = k9_gleam.parse(input)

  // Render the AST back to K9 format
  let output = k9_gleam.render(component)
}
----

== API Overview

=== Top-Level Convenience Functions

`k9_gleam.parse(input: String) -> Result(Component, ParseError)`::
  Parse a K9 file string into a `Component`. Delegates to `parser.parse`.

`k9_gleam.render(component: Component) -> String`::
  Render a `Component` back to K9 surface syntax. Delegates to `renderer.render`.

=== Modules

`k9_gleam/types`::
  Core data types for the K9 AST.

`k9_gleam/parser`::
  Parser implementation. Accepts `.k9` and `.k9.ncl` content.

`k9_gleam/renderer`::
  Renderer that produces K9 surface syntax from the AST.

=== Key Types

[cols="1,3"]
|===
| Type | Description

| `Component`
| Top-level AST node. Contains pedigree, security, target, recipes,
  validation, content map, and tags.

| `Pedigree`
| Identity metadata: name, version, description, author, license.

| `SecurityLevel`
| Trust tier enum: `Kennel`, `Yard`, or `Hunt`.

| `SecurityPolicy`
| Security level plus permission flags (network, filesystem write, subprocess).

| `Target`
| Platform constraints: OS, edge mode, Podman requirement, memory.

| `Recipes`
| Lifecycle recipes: install, validate, deploy, migrate, plus custom recipes.

| `Validation`
| Self-validation block: checksum, pedigree version, hunt authorisation.

| `Contract` / `ContractClause`
| Contractile system integration (must/trust/dust/intend/k9 clauses).
|===

== Dependencies

* `gleam_stdlib` >= 0.44.0
* `gleeunit` (dev only) >= 1.0.0

== Links

* https://hex.pm/packages/k9_gleam[Hex.pm package]
* https://hexdocs.pm/k9_gleam[HexDocs API reference]
* https://github.com/hyperpolymath/standards/tree/main/k9-svc/SPEC.adoc[K9 specification]

== Part of the K9 Ecosystem

This binding is part of the
https://github.com/hyperpolymath/standards/tree/main/k9-svc[K9 Self-Validating Components]
suite within the `standards` monorepo. See
link:../README.adoc[`bindings/README.adoc`] for the full feature matrix across
all five language bindings.
