Examples
Concrete K9 files at each security level, with explanations of what is happening and why.
---
1. Kennel: Project Metadata
Kennel Pure data — safe from any source.
K9!
# project.k9 — Project metadata for a Rust CLI tool
# Security Level: Kennel (pure data, no execution)
---
metadata:
name: panic-attacker
version: 3.2.1
description: Pre-commit validation tool for RSR repositories
author: Jonathan D.A. Jewell
license: PMPL-1.0-or-later
repository:
forge: github
owner: hyperpolymath
name: panic-attacker
default_branch: main
dependencies:
runtime:
- name: nickel
version: ">=1.5.0"
purpose: Contract evaluation
- name: pandoc
version: ">=3.1"
purpose: K9 document processing
build:
- name: rust
version: ">=1.82.0"
tags:
- cli
- validation
- pre-commit
- rsr
This is the simplest K9 form. It starts with the K9! magic bytes, contains only structured data, and declares its pedigree in the metadata section. Any tool can parse this safely — there is nothing to evaluate, nothing to execute. The file is self-describing: you know what it is, who wrote it, and what license governs it without consulting any external source.
---
2. Kennel: Container Deployment Manifest
Kennel Deployment data for a container orchestrator.
K9!
# deploy-manifest.k9 — Stapeln deployment for the K9 service
# Security Level: Kennel (data only)
---
metadata:
name: k9-svc-deploy
version: 1.0.0
description: Deployment manifest for k9-svc container
license: PMPL-1.0-or-later
deployment:
image: cgr.dev/hyperpolymath/k9-svc:1.0.0
replicas: 3
port: 8443
protocol: https
resources:
cpu_limit: "500m"
memory_limit: "256Mi"
cpu_request: "100m"
memory_request: "128Mi"
health_check:
path: /healthz
interval_seconds: 30
timeout_seconds: 5
environment:
K9_LOG_LEVEL: info
K9_TRUST_STORE: /etc/k9/trust
K9_SIGNATURE_VERIFY: "true"
volumes:
- name: trust-store
mount_path: /etc/k9/trust
read_only: true
Even deployment manifests can be Kennel-level. The container orchestrator reads this data and acts on it, but the manifest itself does not execute anything. The K9! magic and pedigree let tooling identify this as a K9 component rather than generic YAML.
---
3. Yard: CI/CD Configuration with Contracts
Yard Nickel evaluation with contract validation.
# ci-config.k9.ncl — CI/CD pipeline configuration
# Security Level: Yard (contracts and types, no execution)
let pedigree = import "pedigree.ncl" in
let ci_contracts = import "ci-contracts.ncl" in
pedigree.K9Pedigree & {
metadata = {
name = "ci-pipeline",
version = "2.1.0",
description = "CI/CD pipeline for pandoc-k9",
},
security = {
trust_level = 'Yard,
allow_network = false,
allow_filesystem_write = false,
allow_subprocess = false,
},
# Nickel contracts enforce structural rules at type-check time
pipeline | ci_contracts.Pipeline = {
stages = [
{
name = "lint",
image = "cgr.dev/hyperpolymath/ci-base:latest",
commands = ["just lint", "just check-format"],
timeout_minutes | ci_contracts.Timeout = 10,
},
{
name = "test",
image = "cgr.dev/hyperpolymath/ci-base:latest",
commands = ["just test"],
timeout_minutes | ci_contracts.Timeout = 30,
needs = ["lint"],
},
{
name = "build",
image = "cgr.dev/hyperpolymath/ci-base:latest",
commands = ["just build"],
timeout_minutes | ci_contracts.Timeout = 20,
needs = ["test"],
},
],
# Contract: at least one stage must exist
# Contract: timeout_minutes must be between 1 and 120
# Contract: 'needs' references must name existing stages
# These are enforced by ci_contracts.Pipeline — not by comments
},
validation = {
checksum = "a1b2c3d4e5f6...",
pedigree_version = "1.0.0",
hunt_authorized = false,
},
}
This is where K9 diverges from static data formats. The ci_contracts.Pipeline contract is not a schema validated externally — it is applied during Nickel evaluation and rejects invalid configurations at type-check time. If you set timeout_minutes = 200, the contract fails before the file is ever used by a CI runner. The allow_subprocess = false declaration is enforced by the K9 runtime: even though this is Nickel code, it cannot spawn processes.
---
4. Hunt: Setup Script with Signed Recipes
Hunt Executable recipes — cryptographic signature required.
# setup.k9.ncl — Project setup with executable recipes
# Security Level: Hunt (execution, signature REQUIRED)
#
# K9-Signature: ed25519:JDAJewell:2026-03-16:a8f9c2...
let pedigree = import "pedigree.ncl" in
pedigree.K9Pedigree & {
metadata = {
name = "project-setup",
version = "1.0.0",
description = "Initial setup for pandoc-k9 development environment",
},
target = {
os = 'Linux,
is_edge = false,
requires_podman = true,
},
security = {
trust_level = 'Hunt,
allow_network = true,
allow_filesystem_write = true,
allow_subprocess = true,
},
validation = {
checksum = "b7e4f8a1c3d9...",
pedigree_version = "1.0.0",
hunt_authorized = true,
},
# Recipe blocks — these actually execute
recipes = {
install = m%"
#!/bin/sh
set -euo pipefail
echo "Installing pandoc-k9 dependencies..."
cargo install nickel-lang-cli
cargo install pandoc-k9-tools
echo "Done."
"%,
validate = m%"
#!/bin/sh
set -euo pipefail
nickel typecheck src/contracts/*.ncl
just test
"%,
deploy = m%"
#!/bin/sh
set -euo pipefail
podman build -t k9-svc:latest -f Containerfile .
podman push k9-svc:latest cgr.dev/hyperpolymath/k9-svc:latest
"%,
migrate = m%"
#!/bin/sh
echo "No migration needed for v1.0.0"
"%,
},
}
This is Hunt level. The recipes block contains shell scripts that will actually run on the host. Notice the K9-Signature header — without a valid Ed25519 signature, every conforming K9 tool will refuse to execute these recipes. The pedigree tells you who authored it, the contracts prove it is structurally valid, and the signature proves it has not been tampered with.
The target.requires_podman = true declaration means this component expects a Podman runtime. The security block explicitly declares what I/O capabilities the recipes require. A K9 runtime can enforce these declarations as a sandbox policy.
---
Key Observations
1. Kennel files are always safe. You can accept them from untrusted sources, pipe them through CI, and display them to users without risk.
2. Yard files are safe but powerful. They compute values and enforce contracts, but they cannot reach outside the Nickel evaluator's sandbox.
3. Hunt files are powerful but accountable. Every execution is traceable to a signed author, a specific version, and a validated contract.
4. The pedigree is always present. At every level, you know the component's name, version, and capabilities before you process it.