What is a Holon

Everything is whole and part

Build a Capability and run it on its own. Compose it into a larger system and it still runs the same way - the same input, the same output, the same behavior. Nothing breaks. Nothing changes.

That isn't a happy coincidence. It's the structural principle every entity is built on. Every entity you create is both whole and part - simultaneously complete on its own and composable into something larger. Your Capability is whole. When it becomes part of a Steward, it stays whole. That's holonic architecture: every entity is a self-sufficient unit that composes into systems of any scale without losing what it is.

The word comes from Arthur Koestler: a holon is something that is, at the same time, a whole and a part. The "Janus face" - looking inward as a complete thing, outward as a participant.

The holons, in the order you'd build them

• Capability - the thing you know how to do. A complete input contract, an output shape, an implementation, and optional guardrails. It runs standalone. Register it in an Operation and nothing about it changes; it doesn't need to know it's inside one.
• Agent - a directed AI collaborator. You define what it knows, what it answers, what it produces. Composed alongside other entities, it stays distinct.
• Governance (guardrails) - the boundary you define for your own work. Not a rule imposed from above, but a constraint you craft and attach. A Capability with guardrails carries them everywhere it goes.
• Workflow - a sequence of steps with evolving state: branching, looping, and composition at each step. It brings its full sequence as a whole.
• Operation - what your Steward knows how to do. It composes Capabilities and Agents into a named, runnable action with its own execution context. The Steward runs the Operation but can't reach inside it.
• Steward - the composition surface. Register capabilities, operations, agents, and guardrails; run them together. A Steward is complete at any scope - it runs on its own, nests inside a larger Steward, or both.

import { Operation } from 'jsr:@fathym/steward/operations';

// FormatText - the same Capability you'd build standalone.
// Nothing about it changes when composed into an Operation.
const FormatOp = Operation('FormatOp', 'Formats text')
  .Capabilities({ FormatText }) // registered; it doesn't know it's here
  .Execute(async (ctx) => ctx.Capabilities.FormatText({ text: 'hello', style: 'title' }));

At every level, each entity remains itself. FormatText inside FormatOp is the same FormatText you built standalone. A Steward nested inside a larger Steward stays independent.

The two tendencies: Self-Assertion and Integration

Every entity carries two tendencies at once:

Tendency	What it means	In code
Self-Assertion (S-A)	Preserves its own identity and lifecycle	.Execute() - the entity runs its own logic
Integration (INT)	Functions as part of a larger system	Governance oversight, IoC service resolution, type accumulation, and Buildable participation

These aren't opposites - they're both active at once. A Capability has S-A because it owns its execution. It has INT because it participates in the Operation's context. The tension between them is what makes composition work without losing identity.

INT is broader than governance alone. Declaring .Services() dependencies is INT (integrating into the IoC graph). Builder generics accumulating by intersection is INT (the type system encoding participation). A builder yielding build authority to the Engine as a Buildable is INT. Governance is the most visible expression, but all four are always active.

The no-aggregation rule

Each entity's guardrails run independently. Your Capability's guardrails don't automatically apply to the Steward that hosts it - and the Steward's guardrails don't automatically reach down to the Capability. Each entity is self-governing.

That's what makes composition safe: no hidden cross-contamination, no surprises when you compose entities from different sources. It's also why you can reason about a holon in isolation - nothing outside it silently changes what it does.

The entity taxonomy

Entities group into three categories by their primary role:

Category	Entities	Role
Behavioral	Capability, Agent, Governance, Workflow	Own their execution (S-A primary)
Execution context	Steward	Hosts behavioral entities (INT primary)
Strategy	Operation	Prescribes how to act on the behavioral holons in context

Operations don't carry their own S-A/INT tension - they make that tension productive by prescribing how behavioral holons collaborate inside a context.

---

• Builder, Runner, Engine → - how a holon goes from definition to execution