Elegy Integration

Authority Split

Elegy and Holon have a clear handoff:

• Elegy owns portable governed artifacts: schemas, fixtures, manifests, compatibility metadata, and reusable contract vocabulary.
• Holon owns workspace runtime authority: execution, policy evaluation, approvals, secrets, runs, evidence, adapter bindings, UX, and local state.

Area	Belongs in Elegy when...	Belongs in Holon when...
Skill definition	Portable governed capability contract.	Imported, profiled, approved, invoked, or persisted in a Holon workspace.
Capability definition	Reusable behavior independent of one host.	Bound to a concrete workspace, dependency, secret, approval, or evidence trail.
Workflow graph	Neutral serialized graph shape or fixture.	Versioned, scheduled, run, cancelled, or evidenced in a Holon workspace.
Crystallized capability	Portable deterministic artifact shape useful across hosts.	Frozen tool with Holon provenance, validation, policy, fallback, secrets, and runtime status.

Import Flow

Holon imports Elegy contracts through SkillSourceKind::ElegyV2:

1. A SkillSourceDescriptor of kind ElegyV2 is registered in the runtime.
2. ImportElegyV2SkillDefinitionRequest accepts a supplied JSON object.
3. The runtime normalizes the Elegy skill definition onto Holon's SkillDefinitionRecord and CapabilityBindingRecord.
4. Normalized entries appear in the CapabilityCatalog under origin ImportedState.
5. Imported capabilities are read-only catalog entries until Holon approves them for execution.

Execution Gating

An Elegy-imported capability is NOT automatically executable:

• It must have usable input and output schemas.
• It must have declared side-effect metadata.
• Its required dependencies and secrets must be resolvable in the local workspace.
• Holon policy must approve the execution posture for the current run context.
• Without these, the capability catalog entry exists but the executor returns UnsupportedCapability.

Currently, only BuiltInProvider capabilities are executable under BuiltInSafe posture. Elegy-imported capabilities will become executable when broader execution postures (model-invoked, adapter-forwarded) are implemented.

Type Mapping

Elegy InvocationResponse → Holon

Elegy field	Holon mapping
InvocationResponse.status	Maps to ExecutorStatus (Completed / Failed / Blocked)
InvocationResponse.output	Becomes ExecutorOutcome.output_json
InvocationResponse.failure	Maps to ExecutorFailure with kind and message
InvocationResponse.events	Converted to ExecutorEvidenceDraft records
InvocationResponse.run_metadata	Stored as evidence with source elegy-invocation

Elegy StructuredFailure → Holon

Elegy field	Holon mapping
StructuredFailure.kind	Maps to StructuredFailureKind (schema mismatch, extraction failure, etc.)
StructuredFailure.message	Preserved verbatim in StructuredFailure.message
StructuredFailure.details	Preserved in StructuredFailure.details
StructuredFailure.source (Elegy-only)	Stored as evidence with source elegy-failure

Elegy ExecutionEvent → Holon

Elegy field	Holon mapping
ExecutionEvent.timestamp	Normalized to created_at_unix_seconds
ExecutionEvent.kind	Maps to WorkflowEventKind
ExecutionEvent.payload	Stored as event payload_json
ExecutionEvent.source	Preserved in evidence source field

Candidate Portable Contract

The candidate Elegy-side artifact for frozen-tool portability is CrystallizedCapabilityDefinition (not a Holon FrozenToolRecord).

Minimum portable fields (Elegy side):

• identity, display name, version, lifecycle state
• deterministic implementation descriptor
• parameter/input schema, output schema, and variable slots
• non-secret dependency descriptors
• side-effect claim and determinism claim
• redacted provenance refs (without private workspace logs)
• governance/risk hints
• validation fixture refs
• compatibility metadata
• optional portable secret-slot descriptors by purpose (e.g. "openai_api_key") without Holon secretRef bindings or values

Holon-only fields (never portable):

• workspace IDs, goal IDs, run IDs, evidence IDs
• approval records and user review decisions
• local trust decisions and policy profile
• secret refs and all secret values
• local dependency probe state
• adapter session handles and adapter binding state
• fallback state, circuit breaker state, and failure counters

Forge Status

elegy-forge is deferred until Holon proves reusable deterministic materialization. No Forge work is required for the current implementation slice.

Read Next

• Tooling Taxonomy
• Architecture