gen-bind

Module binding with external arguments for Nix — partial application of bindings into NixOS module functions with closure-based injection, collision detection with blame, lazy contracts, and thunk resolution for config-dependent values.

gen-bind gives you what manual specialArgs doesn't: builtins.functionArgs introspection to inject only the args a module actually declares, merge strategy control when bindings collide with module-system args, contract assertions that fire on demand rather than at wrap time, and provenance tracking that names the source in every error message.

Terminology

Term	Definition
Bindings	Named external values injected into module functions
Wrapping	Partial application of bindings into a module's args
Merge Strategy	Resolution policy when a binding name collides with a module-system arg
Thunk	Config-dependent deferred value resolved inside `evalModules`
Contract	Lazy assertion on a binding value (checked on demand, not at wrap time)
Provenance	Source-tracking metadata surfaced in blame messages on collision or violation
Signature	Static record of what a module requires, what was bound, and what remains

Gen Ecosystem

Library	Role
gen-algebra	Pure primitives (search, record, identity)
gen-schema	Typed registries (kinds, instances, collections, refs)
gen-aspects	Aspect types (traits, classification, dispatch)
gen-graph	Graph queries (combinators, traversals, fixpoint)
gen-scope	Scope graphs (construction, evaluation, resolution)
gen-select	Selector algebra (pattern matching over graph positions)
gen-bind	Module binding (inject args into NixOS modules)
gen-derive	Rule dispatch (stratified phases, fixpoint, conflict resolution)

Quick Start

As a flake input

# flake.nix
{
  inputs.gen-bind.url = "github:sini/gen-bind";
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

  outputs = { gen-bind, nixpkgs, ... }:
    let
      bindLib = gen-bind.lib;
      # or: bindLib = import ./path/to/gen-bind/nix/lib { lib = nixpkgs.lib; };
    in {
      # Wrap a module with external bindings
      wrappedModule = (bindLib.wrap {
        module = { host, config, lib, ... }: {
          networking.hostName = host.name;
        };
        bindings = { host = { name = "igloo"; }; };
      }).module;
    };
}

Programmatic use

let
  bindLib = import ./path/to/gen-bind/nix/lib { inherit lib; };
  result = bindLib.wrap {
    module = { host, pkgs, config, ... }: {
      environment.systemPackages = [ pkgs.git ];
      networking.hostName = host.name;
    };
    bindings = { host = { name = "igloo"; }; };
    # pkgs comes from evalModules specialArgs — wrap only injects `host`
  };
in result.module  # function: { pkgs, config, ... } -> { ... }

Without flakes

let
  bindLib = import ./path/to/gen-bind/nix/lib { inherit lib; };
in
# use bindLib.wrap, bindLib.wrapAll, bindLib.contract, etc.

Core Concepts

Bindings and Wrapping

wrap inspects a module's formal parameters via builtins.functionArgs and injects only the bindings that match. Non-matching bindings are ignored. The result is a partially-applied module whose remaining args come from evalModules as normal.

result = bindLib.wrap {
  module = { host, config, lib, ... }: {
    networking.hostName = host.name;
  };
  bindings = { host = { name = "igloo"; }; extraUnused = "ignored"; };
};

# result.module   — partially applied: { config, lib, ... } -> { ... }
# result.wrapped  — true
# result.signature — { requires = { config = false; lib = false; }; bound = { host = { ... }; }; ... }

When no binding names match the module's args, the module passes through unchanged (result.wrapped = false).

Module Shapes

wrap handles three module shapes:

Function — standard { arg1, arg2, ... }: { ... }. Bindings are injected via partial application.
Imports attrset — { imports = [ mod1 mod2 ]; }. Each import is wrapped recursively.
Plain attrset — { config = { ... }; }. Passes through unchanged.

Merge Strategies

When a binding name collides with a module-system arg (e.g., both gen-bind and evalModules provide lib), the merge strategy determines resolution:

result = bindLib.wrap {
  module = { lib, host, ... }: { networking.hostName = host.name; };
  bindings = { host = { name = "igloo"; }; lib = myCustomLib; };
  mergeStrategies = {
    lib = bindLib.mergeStrategy.systemWins;  # module-system lib wins
    # or: bindLib.mergeStrategy.bindWins (default)
    # or: bindLib.mergeStrategy.error (throw at eval time)
  };
};

The default strategy is bindWins — binding shadows the module-system arg. Set _mergeStrategy directly on a binding value as an inline annotation:

bindings = {
  lib = myLib // { _mergeStrategy = "system-wins"; };
};

Collision detection runs when mkMergeValidator is called with the module args. Warnings (for bindWins/systemWins) and errors (for error) include provenance if set.

Config Thunks

Some bindings depend on the evalModules fixpoint — they can't be computed until config is available. Use mkThunk to defer resolution:

result = bindLib.wrap {
  module = { extraModules, config, ... }: {
    imports = extraModules;
  };
  bindings = {
    extraModules = [
      # Static entry
      myBaseModule
      # Thunk — resolved when evalModules calls the wrapper
      (bindLib.mkThunk ({ config }: lib.optional config.services.nginx.enable nginxExtraModule))
    ];
  };
};

Thunks travel as markers ({ __configThunk = true; __fn = fn; }) through the binding pipeline and resolve inside the module wrapper when evalModules provides config. Only list-valued bindings are auto-detected for thunks. Non-list bindings with thunks require explicit thunkBindings = [ "argName" ].

mkThunkFrom scopeId fn creates a thunk annotated with a source scope for tracing.

Lazy Contracts

Contracts are assertions that fire only when the bound value is demanded — preserving Nix's lazy evaluation semantics. Unbuilt modules have zero contract cost.

result = bindLib.wrap {
  module = { host, ... }: { networking.hostName = host.name; };
  bindings = { host = { name = "igloo"; }; };
  contracts = {
    host = bindLib.contract.hasFields [ "name" "system" ];
    # or: bindLib.contract.isType "set"
    # or: bindLib.contract.nonEmpty
    # or: bindLib.contract.mk { check = v: v.name != ""; message = "host must have non-empty name"; }
  };
  provenance = {
    host = { source = "entity-context"; scope = "host=igloo"; };
  };
};

Contract violations include the message and provenance:

gen-bind: contract violation: value must have fields: name, system (provided by 'entity-context' at scope 'host=igloo')

contract.apply contract value prov applies a contract directly without going through wrap.

Provenance

Provenance metadata on the wrap call surfaces in all blame messages — collisions, contract violations, and error-strategy throws:

bindLib.wrap {
  module = myModule;
  bindings = { host = hostVal; };
  provenance = {
    host = { source = "scope-policy"; scope = "host=igloo,user=tux"; };
  };
};

provenance.format prov formats a provenance record to a string ("provided by 'scope-policy' at scope 'host=igloo,user=tux'") or returns "" for null.

Signatures

Every wrap result includes a signature describing the module's binding interface:

result.signature
# -> {
#     requires = { config = false; lib = false; };  # still needed from evalModules
#     bound = { host = { optional = false; provenance = { source = "..."; }; }; };
#     unsatisfied = [];  # vocabulary keys present but not injected
#     mergeStrategies = { host = "bind-wins"; };
#   }

buildSignature computes the signature from a module + binding config without performing wrapping.

Layered Composition

Multiple binding sources (entity context, enrichment, pipes) compose with later layers shadowing earlier ones:

# compose: plain attrset merge
allBindings = bindLib.compose [
  entityBindings
  enrichmentBindings
  pipeBindings
];

# composeWith: structured merge across all binding fields
cfg = bindLib.composeWith [
  { bindings = entityBindings; provenance = entityProv; }
  { bindings = enrichBindings; contracts = enrichContracts; }
  { bindings = pipeBindings; mergeStrategies = pipeStrats; }
];
# cfg.bindings, cfg.provenance, cfg.contracts, cfg.mergeStrategies — all merged

result = bindLib.wrap (cfg // { module = myModule; });

Identity Wrapping

NixOS deduplicates modules by key. wrapIdentity stamps a stable key onto a wrapped module so that re-emitting the same module at the same identity doesn't duplicate it in evalModules:

keyed = bindLib.wrapIdentity {
  class = "nixos";
  module = result.module;
  identity = "host=igloo";
  # isAnon = false;  # default: sets key + _file + imports wrapper
};
# keyed -> { key = "nixos@host=igloo"; _file = "nixos@host=igloo"; imports = [ result.module ]; }

Set isAnon = true to use lib.setDefaultModuleLocation instead — useful for anonymous modules that shouldn't appear in key-based dedup.

Arg Stripping

After wrapping, binding arg names must be removed from the module's advertised args. Otherwise evalModules probes _module.args.<name> for every advertised arg and crashes when the key doesn't exist.

stripped = bindLib.stripBindingArgs {
  module = result.module;
  bindingNames = [ "host" ];
};

Works on both function modules and attrset modules with __functionArgs. Args not present in the module's advertised interface are silently skipped.

Batch Wrapping

wrapAll wraps a list of modules with shared bindings, pre-computing contracts once across all modules:

batch = bindLib.wrapAll {
  modules = [ modA modB modC ];
  bindings = sharedBindings;
  contracts = sharedContracts;
  provenance = sharedProv;
};

# batch.modules    — list of wrapped modules
# batch.validators — list of non-null validators (one per wrapped function module)
# batch.signatures — list of signatures (one per module)
# batch.all        — wrapped modules ++ non-null validators (flat list)

API Reference

`wrap`

wrap {
  module,                          # function | { imports = [...]; } | attrset
  bindings ? {},                   # { name = value; } — external values to inject
  contracts ? {},                  # { name = contract; } — lazy assertions per binding
  provenance ? {},                 # { name = { source; scope?; }; } — blame metadata
  mergeStrategies ? {},            # { name = strategy; } — per-arg collision resolution
  defaultMergeStrategy ? bindWins, # fallback strategy for unspecified args
  thunkBindings ? [],              # explicit list of list-valued args containing thunks
}

Returns { module; wrapped; validator; signature; advertisedArgs }.

module — wrapped or passthrough module
wrapped — true if any binding was injected
validator — mkMergeValidator result for collision checking, null if no bindings matched
signature — buildSignature result
advertisedArgs — remaining formal args after binding injection

`wrapAll`

wrapAll {
  modules,          # list of modules
  bindings ? {},
  contracts ? {},
  provenance ? {},
  mergeStrategies ? {},
  defaultMergeStrategy ? bindWins,
  thunkBindings ? [],
}

Contracts are pre-computed once and shared across all modules. Returns { modules; validators; signatures; all }.

modules — list of wrapped modules
validators — list of non-null validators
signatures — list of signatures (one per module)
all — modules ++ validators (flat list of wrapped modules and non-null validators)

`mkThunk`

mkThunk fn

Creates a config-dependent thunk. fn receives { config; <ctx-args>... } — ctx-args are any of fn's named parameters that exist in the binding context. The return value is spliced into the list binding (single value or list both work).

`mkThunkFrom`

mkThunkFrom scopeId fn

Like mkThunk but annotates the thunk with a source scope string for tracing.

`isThunk`

isThunk value  # -> bool

Returns true if value is a thunk created by mkThunk or mkThunkFrom.

`resolveThunks`

resolveThunks { config; ctx; thunkArgNames; bindings; }

Resolves thunks within list-valued bindings. For each arg name in thunkArgNames whose binding is a list, expands thunk entries by calling __fn with config and matching ctx args. Non-thunk entries and non-list args pass through unchanged.

`contract.mk`

contract.mk { check; message ? "contract violation"; blame ? null; }

Creates a contract. check is value -> bool. blame is an optional string added to the error message.

`contract.hasFields`

contract.hasFields fields  # fields: [ "name" "system" ]

Contract asserting the value has all listed fields.

`contract.isType`

contract.isType type  # type: "set" | "list" | "string" | "int" | "bool" | ...

Contract asserting builtins.typeOf value == type.

`contract.nonEmpty`

Contract asserting the value is non-empty (non-empty list, non-empty attrset, or non-null).

`contract.apply`

contract.apply contract value prov

Applies a contract directly. Returns value if the check passes, throws with message + provenance string on failure.

`mergeStrategy`

mergeStrategy.bindWins    # "bind-wins"   — binding shadows module-system arg (default)
mergeStrategy.systemWins  # "system-wins" — module-system arg wins, binding dropped
mergeStrategy.error       # "error"       — throw at eval time with blame

mergeStrategy.fromBindings bindings
# -> { name = strategy | null; } — extracts _mergeStrategy annotations from binding values

`mkMergeValidator`

mkMergeValidator { resolvePolicy; boundArgNames; provenance; }

Returns a validator function moduleArgs -> { warnings }. Call with the module args attrset (including config._module.args) to check for collisions. Error-strategy collisions throw immediately (builtins.seq forces the check list to WHNF). Bind-wins and system-wins collisions produce warning strings in .warnings.

`provenance.format`

provenance.format prov  # prov: { source; scope?; } | null

Returns a formatted string ("provided by 'source' at scope 'scope'") or "" for null.

`compose`

compose layers  # layers: [ attrset ... ]

Plain left-fold // across binding attrsets. Later layers shadow earlier ones.

`composeWith`

composeWith layers
# layers: [ { bindings?; provenance?; contracts?; mergeStrategies?; } ... ]

Structured composition across all four binding fields. Returns { bindings; provenance; contracts; mergeStrategies }.

`wrapIdentity`

wrapIdentity { class; module; identity; isAnon ? false; }

Stamps a stable NixOS module key onto a module. Non-anon: returns { key = "${class}@${identity}"; _file = ...; imports = [ module ]; }. Anon: calls lib.setDefaultModuleLocation instead.

`stripBindingArgs`

stripBindingArgs { module; bindingNames; }

Removes bindingNames from the module's advertised formal args. Works on function modules and attrset modules with __functionArgs. Returns the module unchanged if no args match or the module shape doesn't support stripping.

`buildSignature`

buildSignature { module; bindings; defaultMergeStrategy; mergeStrategies; provenance ? {}; }

Computes a signature record: { requires; bound; unsatisfied; mergeStrategies }.

requires — formal args not satisfied by bindings (pass to evalModules)
bound — { argName = { optional; provenance; }; } for each injected arg
unsatisfied — arg names in vocabulary but not injected and not optional (currently always [] with the standard API)
mergeStrategies — per-bound-arg strategy

Laziness Guarantees

Binding values are never forced at wrap time — builtins.functionArgs introspects without evaluating.
Per-arg injection uses // semantics — only args the module actually demands are forced.
Contracts fire on demand only — the contract thunk wraps the binding value in an assert; if the module never demands the arg, the contract never runs.
Unbuilt hosts have zero cost — thunks in list bindings resolve only when the wrapper function is called by evalModules.

Architecture

External bindings (entity context, enrichment, pipes)
  | composed via
compose / composeWith
  | applied via
wrap / wrapAll
  |-- builtins.functionArgs — inspect module signature
  |-- applyContracts — lazy assertion wrapping (cf. Chitil 2012 §4.2)
  |-- resolvePolicy — per-arg merge strategy dispatch (cf. Leijen 2005 §2)
  |-- detectThunkArgs — identify config-dependent list bindings
  '-- wrapFunctionModule / wrapImportsModule / passthrough
        | result
      { module; wrapped; validator; signature; advertisedArgs }
        | optional post-processing
      wrapIdentity — NixOS key stamping (cf. Cardelli 1997 §5)
      stripBindingArgs — formal arg cleanup
      mkMergeValidator — collision detection with blame (cf. Findler 2002 §2)

File Layout

nix/lib/
  default.nix        — public API surface
  wrap.nix           — core wrapping logic (wrapCore, wrapAllCore)
  merge-strategy.nix — collision detection and merge validator
  contract.nix       — lazy binding contracts (mk, hasFields, isType, nonEmpty, apply)
  thunk.nix          — config thunk primitives (mkThunk, mkThunkFrom, isThunk, resolveThunks)
  provenance.nix     — blame formatting
  compose.nix        — layered composition (compose, composeWith)
  identity.nix       — NixOS module identity wrapping
  strip.nix          — binding arg stripping for NixOS compatibility
  signature.nix      — module signature inference

Testing

Tests use nix-unit in ci/:

cd ci
nix develop --override-input gen-bind ../.. -c nix-unit \
  --override-input gen-bind ../.. --flake .#.tests

Theoretical Foundations

gen-bind's design draws on five papers. Each is either implemented (the paper's formalism directly shapes the code) or informed by (the paper's concepts influenced the approach without direct implementation).

Implements

Feature	Paper	Relationship
Blame tracking	Findler & Felleisen -- Contracts for Higher-Order Functions (ICFP 2002)	Provenance metadata plays the role of Findler's blame labels: when a contract fires or a collision is detected, the error message identifies the guilty party (binding source, scope rule) via the same covariant/contravariant blame assignment structure (cf. Findler 2002 S2.3).
Lazy contracts	Chitil -- Practical Typed Lazy Contracts (ICFP 2012)	Contracts are partial identities (`assert c` is less than or equal to `id` -- Chitil 2012 S4.2) that fire on demand. gen-bind contracts wrap binding values in exactly this pattern: the assertion thunk is never forced unless the consuming module demands the arg (cf. Chitil 2012 S2).
Module signatures	Cardelli -- Program Fragments, Linking, and Modularization (POPL 1997)	gen-bind's `signature.requires` and `signature.bound` are a lightweight analog of Cardelli's linkset interfaces: each compilation unit (wrapped module) declares what it provides (bound args) and what it still needs (requires from evalModules). Identity wrapping implements Cardelli's fragment naming for dedup (cf. Cardelli 1997 S5).

Informed by

Feature	Paper	Relationship
Closure-based binding	Reynolds -- Definitional Interpreters for Higher-Order Programming Languages (1972)	Reynolds' closure environments inform the approach but gen-bind's wrapping is partial application, not defunctionalization per se. `builtins.functionArgs` is the Nix analogue of formal parameter reflection in a definitional interpreter (cf. Reynolds 1972 S4).
Merge resolution	Leijen -- Extensible Records with Scoped Labels (TFP 2005)	Leijen's free extension (retaining duplicate labels with scoped resolution) informs the merge strategy vocabulary: `bindWins` shadows like Leijen's first-match selection; `error` mirrors strict extension where duplicates are rejected (cf. Leijen 2005 S2). gen-bind uses flat `//` rather than row-typed scoping.

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.github		.github
ci		ci
nix/lib		nix/lib
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
default.nix		default.nix
flake.lock		flake.lock
flake.nix		flake.nix

Folders and files

Latest commit

History

Repository files navigation

gen-bind

Table of Contents

Terminology

Gen Ecosystem

Quick Start

As a flake input

Programmatic use

Without flakes

Core Concepts

Bindings and Wrapping

Module Shapes

Merge Strategies

Config Thunks

Lazy Contracts

Provenance

Signatures

Layered Composition

Identity Wrapping

Arg Stripping

Batch Wrapping

API Reference

wrap

wrapAll

mkThunk

mkThunkFrom

isThunk

resolveThunks

contract.mk

contract.hasFields

contract.isType

contract.nonEmpty

contract.apply

mergeStrategy

mkMergeValidator

provenance.format

compose

composeWith

wrapIdentity

stripBindingArgs

buildSignature

Laziness Guarantees

Architecture

File Layout

Testing

Theoretical Foundations

Implements

Informed by

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`wrap`

`wrapAll`

`mkThunk`

`mkThunkFrom`

`isThunk`

`resolveThunks`

`contract.mk`

`contract.hasFields`

`contract.isType`

`contract.nonEmpty`

`contract.apply`

`mergeStrategy`

`mkMergeValidator`

`provenance.format`

`compose`

`composeWith`

`wrapIdentity`

`stripBindingArgs`

`buildSignature`

Packages