Modules

Omega has two layers of module structure: the module artifact layer (compiled, hashed, sealed ModuleVals with attenuated capabilities) and the package layer (define-package + require + provide for organizing libraries on disk).

Defining a package

The canonical pattern (from projects/omega-lisp/packages/agents/lib/agents.lisp):

lisp

;; Canonical package declaration.
(define-package "agents"
  :description "Agent delegation with amb-based selection"
  :exports '(agents)
  :effects '(agent.spawn.op agent.run.op)
  :requires '()
  :version "0.1.0"
)

(require 'agents/providers)
(require 'agents/selection)

(define (agents error-description)
  "Root package API: delegate to amb-based agent selection."
  (amb-agent-fix error-description))

(provide 'agents)

Key forms:

define-package — manifest at the top of a package's root file.
require — load another package by name; idempotent (won't reload).
provide — finalize the current package's exports.

Loading a package by file path uses load:

lisp

(load "lib/plm/core.lisp")    ; loads each time, does NOT mark as required

Available packages (snapshot)

From CLAUDE.md § Package System:

Package	Description
`plm/core`	Document abstraction for RLM-style processing
`plm/chunking`	Chunking strategies
`plm/search`	amb-based document search with backtracking
`aliases/clojure`	Clojure-style syntax (defn, fn, ->, ->>)
`workflow/stage`	Workflow stage definitions
`workflow/pipeline`	Topological-sort pipeline
`self-healing`	Fixpoint-based self-healing builds
`monad`	Monadic operations
`agents`	amb-based agent selection

The full set of installed packages is enumerated by :packages in the REPL.

The artifact layer

ModuleArtifact (core/modules/artifact.ts) is the compiled form of a package. It carries:

The compiled Expr tree.
A content hash (hashText — currently a stub; production uses crypto hashing).
The export map.
Any required-ness annotations.

compileModule.ts is the compiler; instance.ts is the loader that turns artifacts into live ModuleVals with attenuated capability sets.

Sealed modules

A ModuleVal (tag: "Module" in the Val union) carries a sealed environment with a limited capability set. The capability set is attenuated on import — the module sees only the capabilities its caller chose to grant. This is the basis for safe code loading (e.g., loading user-supplied scripts without giving them filesystem access).

Module graph

core/modules/graph.ts tracks the dependency graph between modules. require consults the graph to detect cycles and dispatch to the correct compile order. The graph is the input to pipeline-execution-order for any module-aware build orchestration.

Modules ​

Defining a package ​

Available packages (snapshot) ​

The artifact layer ​

Sealed modules ​

Module graph ​