Fathym
Menu

Advanced Patterns

These go beyond the base holonic contract. For the base patterns (Builder/Runner/Engine, carry-forward generics, IDD), see Creating Holons.

Builder strategy functions

Any holon builder can store strategy functions alongside schemas and service factories - an executable value declared on the builder, stored in the module, and called by the engine at a defined lifecycle moment. (This is distinct from schema renaming: strategy functions store behavior, not schemas.)

The division of labor is strict: Build() stores the function; it does not call it. The engine decides when to call it. (The one exception is .Governance() - the policy builder is built immediately when the module is constructed, because governance must exist before engine startup.)

// BUILDER - TitleCase public method stores a camelCase protected field
public Validates(fn: (ctx: MyContext) => Promise<void>): this {
  this.validateFn = fn;
  return this;
}

// MODULE - same name as a readonly field
readonly Validates?: (ctx: MyContext) => Promise<void>;

// ENGINE - calls the stored fn at the right moment; Build() never does
if (module.Validates) await module.Validates(ctx);

// USAGE
const MyHolon = Capability("Example", "...")
  .Input(z.object({ value: z.string() }))
  .Output(z.object({ result: z.string() }))
  .Validates(async (ctx) => {
    if (ctx.Input.value.length === 0) throw new Error("Value cannot be empty");
  })
  .Execute(async (ctx) => ({ result: ctx.Input.value.toUpperCase() }));

The four-layer vocabulary rule

When you add a strategy function (or any new builder concept), the same name must appear in all four layers: builder method → module field → engine call site → intent method name. Keeping the vocabulary identical across layers is what keeps a holon legible - there's one name for one concept, everywhere.

Orchestrating holons - an inner Steward

Some behavioral holons also host their own inner Steward - they compose sub-capabilities and sub-tools, run Configure/Start lifecycle, and clone their builder on write so each instance stays isolated. This is the pattern behind @fathym/power-ai's vaults and workbenches: a vault is a behavioral holon and a Steward at its core, which is why .Configure() is where you add a vault's domain operations and agents. The holon stays whole; its inner Steward is how it composes the layer beneath it.

This guide is an overview of the advanced surface; the exhaustive reference lives in the @fathym/steward repository docs (docs/guides/advanced-holon-patterns.md).

On this page