Skip to main content

Hydra-Kernel

The Hydra kernel — the code that fundamentally defines what Hydra is and how it operates. Hydra's core data types (Type, Term, Graph, Module, etc.) and its fundamental programming logic (inference, checking, reduction, rewriting, validation, the coder framework, the primitive standard library) live here. The kernel uses the Hydra language to define the Hydra language itself.

Every other Hydra package is peripheral, adding capabilities like Haskell or Java support, RDF or property graph functionality, and so on. Every package depends on hydra-kernel; every host language imports a generated form of it.

Hydra is a functional programming language based on the LambdaGraph data model, exploring an isomorphism between typed lambda calculus and labeled hypergraphs. See the main Hydra README for project overview and use cases.

What lives here

packages/hydra-kernel/ is the DSL source of truth for the kernel. There is no generated output in this package — only the hand-written DSL modules that describe what the kernel is. Generated kernels for each host language live in dist/<lang>/hydra-kernel/.

Type modules

src/main/haskell/Hydra/Sources/Kernel/Types/ defines the core data structures:

  • Core.hs — the central grammar: Term, Type, Literal, Function, Elimination, plus annotations and type schemes. The most important file in the kernel.
  • Graph.hs — Graph, Primitive, Library, TermCoder — the runtime containers for terms, types, and primitive bindings. Each Primitive pairs a universal PrimitiveDefinition (from Packaging.hs) with a host-specific native implementation.
  • Packaging.hs — Package, Module, Definition, module/package dependencies, and the EntityMetadata documentation/lifecycle types. See the Packaging wiki page for the model.
  • Coders.hs — the bidirectional Coder framework that every per-language coder builds on, plus Adapter (which transforms both type and value).
  • Errors.hs — the unified error taxonomy used across inference, validation, and code generation.
  • Ast.hs — variant tags used by validators and serializers.
  • Mantle.hs — type-system internals (TypeScheme, kind, class constraints).
  • Subdirectories (Error/, Json/, Show/) — submodule groupings for error variants, JSON encoding, and pretty-printing.

Term modules

src/main/haskell/Hydra/Sources/Kernel/Terms/ defines the algorithms:

  • Inference.hs — Algorithm W (Hindley–Milner) with class constraints, type schemes, and Hydra-specific extensions for nominal terms.
  • Checking.hs — type checking; runs after inference and validates results.
  • Reduction.hs — beta/eta reduction, including tail-call detection used by the Python and Java coders (see TCO implementation).
  • Rewriting.hs — free-variable analysis, substitution, term traversal.
  • Analysis.hs — isSelfTailRecursive and related shared analyses.
  • Validate/ — module-level validation rules (hydra.core.validate.*).
  • Sorting.hs, Topology.hs — Tarjan SCC over module/term dependency graphs.
  • Dsls.hs, Generation.hs — the meta-level pieces that drive sync pipelines.
  • Lexical.hs, Names.hs, Scoping.hs, Variables.hs — binder hygiene, name generation, scope handling.

Library modules — the canonical primitive registry

src/main/haskell/Hydra/Sources/Kernel/Lib/ is the primitive registry: one module per hydra.lib.<sub> namespace, declaring every primitive in that namespace as a PrimitiveDefinition (name, description, signature, isPure / isTotal flags, and an optional cross-compilable default implementation in Hydra terms).

The 21 namespaces — Chars, Defaults, Effects, Eithers, Equality, Files, Functions, Hashing, Lists, Literals, Logic, Maps, Math, Optionals, Ordering, Pairs, Regex, Sets, Strings, System, Text — together declare ~290 primitives (see the lexicon for the authoritative count). See docs/hydra-lexicon.txt for the full signature list, and docs/recipes/adding-primitives.md for the recipe to add a new one.

Host-side primitive registries — including the Haskell-side Hydra/Overlay/Haskell/Libraries.hs (in overlay/haskell since #473, relocated under the hydra.core.overlay.<lang>.* namespace by #501) that pairs each native implementation with a primitive name — are distinct from this canonical registry: they provide host-specific implementations and derive each primitive's name from its generated PrimitiveDefinition (the single source of truth), rather than re-declaring it.

Code organization

The kernel package contains DSL sources only. Generated kernels and runtime helpers live in adjacent directories:

Where What
packages/hydra-kernel/src/main/haskell/Hydra/Sources/ Kernel DSL sources (this package)
heads/haskell/src/main/haskell/Hydra/Dsl/ Hand-written Haskell DSL helpers used to write the sources
overlay/haskell/hydra-kernel/src/main/haskell/Hydra/Overlay/Haskell/Lib/ Hand-written Haskell primitive implementations (overlaid onto the kernel dist)
dist/haskell/hydra-kernel/ Generated Haskell kernel (Hydra/Core.hs, Hydra/Graph.hs, etc.)
dist/java/hydra-kernel/ Generated Java kernel (hydra.core.model.*, hydra.core.graph.*, etc.)
dist/python/hydra-kernel/ Generated Python kernel
dist/scala/hydra-kernel/ Generated Scala kernel
dist/{clojure,common-lisp,emacs-lisp,scheme}/hydra-kernel/ Generated Lisp-dialect kernels
dist/typescript/hydra-kernel/ Generated TypeScript kernel
dist/json/hydra-kernel/ Generated JSON kernel — language-agnostic interchange

For the broader packages/heads/dist pattern, see the Code organization wiki page.

How the kernel is regenerated

The kernel is generated from these DSL sources via bin/sync.sh. After editing a file under Hydra/Sources/Kernel/, run:

heads/haskell/bin/sync-haskell.sh   # regenerate Haskell kernel, run stack test
bin/sync.sh                # regenerate every target language's kernel and tests

See Generating code with Hydra for the full pipeline and The Hydra build system for the cache model.

Extending the kernel

Three of the most common kernel-modification tasks have dedicated recipes:

For the DSL idioms used to write these sources, see the Haskell DSL guide.

See also

Metadata

Release files for hydra-kernel 0.18.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hydra-kernel 0.18.0
File Size Uploaded Provenance Actions
hydra_kernel-0.18.0.tar.gz 775.0 kB Without provenance Details for hydra_kernel-0.18.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hydra-kernel 0.18.0
File Interpreter ABI Platform Actions
hydra_kernel-0.18.0-py3-none-any.whl Python 3 none any Details for hydra_kernel-0.18.0-py3-none-any.whl

Total release size: 1.5 MB

Release files / hydra_kernel-0.18.0.tar.gz

Download URL hydra_kernel-0.18.0.tar.gz
Size 775.0 kB
Tags Source
SHA-256 checksum
How to use checksums
82eba76d7d942cde8c58a2838626ac36eeb5aa0e071d9d0cdd6aa75051e505d4
BLAKE2b-256 checksum
How to use checksums
2ba62098ec673263e45cbe6a1e59dea61f36f70577e7ca4d4c178208ff7e0e6b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.8

Release files / hydra_kernel-0.18.0-py3-none-any.whl

Download URL hydra_kernel-0.18.0-py3-none-any.whl
Size 726.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c5a54618525c057751810584fd056bffe1519a77b47567575681275e448b3269
BLAKE2b-256 checksum
How to use checksums
503b86a0802d3b7c1bfb04f77133ce714eebab7bf17711e1ffbc401056702eca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.8

Security for hydra-kernel 0.18.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page