Concepts
Clamp keeps its vocabulary small on purpose. A tiny CLI and a multi-process platform use the same words.
How the pieces relate
Application (blueprint)
└── Modules
├── Requires → Capability ← Provides (another module)
└── Contributes → Target (e.g. CLI commands)
└── Processes (roots)
└── projection → reachable modules only → Freeze → RunA module relates to the rest of the application in a few explicit ways: it can require a capability, provide one, contribute to a subsystem, and — in the design, not yet the code — participate in lifecycle contracts and own resources.
Glossary
| Term | Meaning | Status |
|---|---|---|
| Application | The architectural blueprint describing a system: which modules exist and which processes can be run from them. A description, not a runtime object. | Prototype |
| Module | The primary extension unit: a composable declaration of functionality that may require capabilities, provide capabilities and contribute composition structure. | Prototype |
| Capability | An ability or access contract available to the running application, such as Clock. Typed. Not arbitrary state, not a service locator. | Prototype |
| Requirement | A module's declared need for a capability. Prefer the abstraction (Clock) over a concrete implementation. | Prototype |
| Provider | A role, not a type: whatever supplies a capability — a module, a value, an adapter. | Prototype |
| Contribution | Something used during composition to assemble another subsystem, such as a CLI command. A capability is used by code at run time; a contribution is consumed while building. | Prototype |
| Process | An independently runnable projection of an application, defined by its root executions and everything they transitively need. | Prototype |
| Freeze | The boundary where composition becomes structurally immutable. Before it, modules and providers can change; after it, the plan is fixed and inspectable. | Prototype |
| Lifecycle | How a process lives: initialize, start, become ready, run, drain, stop. | In progress |
| Kernel | The coordination layer, composed from the minimum mechanisms the selected process needs. Not a monolith and not an entry tax. | Prototype |
| Runtime | What actually drives execution: a thread, an async runtime, a deterministic loop. Kernel coordinates it; it does not implement it. | Planned |
| Foundations | Small primitives the standard library does not provide: clock, identifiers, semantic durations. Common does not mean core. | Clock only |
| Profile | A preset of defaults, recommended modules and policies for a kind of application (CLI, service, worker…). Never a separate framework variant. | Planned |
Rules that shape the vocabulary
- Ambiguity is an error. Two providers for one capability and no explicit selection fails composition. Registration order never picks a winner.
- Replacement is explicit. Swapping a provider is something you state, not something load order does to you.
- Reachability before initialization. A process validates and initializes only what its roots can reach; a broken module in another process does not stop this one.
- Business logic does not depend on transport. An operation must be runnable without the interface that exposed it. Design principle
- Crossing a process boundary is always explicit. No capability silently becomes a network call. Design principle