Mark/mesh-seed

Fork 0

Terminology: template.yaml files are CONTRACT templates, not capability templates #117

New issue

Closed

opened 2026-04-10 22:04:11 +00:00 by Mark · 3 comments

Mark commented

2026-04-10 22:04:11 +00:00

Owner

Critical Terminology Error

The codebase conflates two different concepts:

What template.yaml files actually are:

Contract templates - Define intent interface (input_schema, output_schema, skill_family)
Specify what the transaction expects/requires
Created by intake when intent arrives
Used by workers to understand execution contract

What capabilities actually are:

Skill bundles - Attached to workers at spawn time
Implementation details (which skills worker has loaded)
NOT templates or interfaces

Current Code Confusion

Evidence of misnamed concepts:

CapabilityRegistry loads template.yaml (should be ContractRegistry)
CapabilityRecord has skills field (should be ContractRecord with skill_family)
CapabilityLoader loads template.yaml (should load contract definitions)
AGENTS.md refers to "capability templates" (should be "contract templates")

Impact

This terminology error causes:

Confusion about what capabilities are
Workers treating templates as their identity
Infrastructure mixing contract/interface logic with capability/implementation logic

Fix Required

Rename to contract terminology:
- CapabilityRegistry → ContractRegistry
- CapabilityRecord → ContractRecord
- CapabilityLoader → ContractLoader
- capabilities/_muscle/ → contracts/_muscle/
Clarify in documentation:
- template.yaml = contract template (interface)
- capability = skill bundle attached to worker (implementation)
Separate concerns:
- Contract defines what (input/output expectations)
- Capability defines how (which skills worker uses)

References

Issue #114 - Capabilities as skill bundles discussion
Issue #115 - Factories are workers discussion
Issue #116 - Worker handoff mechanism
AGENTS.md - Needs terminology correction
runtime/capability_registry.py - Should be runtime/contract_registry.py
runtime/capability_loader.py - Should be runtime/contract_loader.py

## Critical Terminology Error The codebase conflates two different concepts: **What template.yaml files actually are:** - **Contract templates** - Define intent interface (input_schema, output_schema, skill_family) - Specify what the transaction expects/requires - Created by intake when intent arrives - Used by workers to understand execution contract **What capabilities actually are:** - **Skill bundles** - Attached to workers at spawn time - Implementation details (which skills worker has loaded) - NOT templates or interfaces **Current Code Confusion** Evidence of misnamed concepts: - `CapabilityRegistry` loads template.yaml (should be `ContractRegistry`) - `CapabilityRecord` has `skills` field (should be `ContractRecord` with skill_family) - `CapabilityLoader` loads template.yaml (should load contract definitions) - AGENTS.md refers to "capability templates" (should be "contract templates") **Impact** This terminology error causes: - Confusion about what capabilities are - Workers treating templates as their identity - Infrastructure mixing contract/interface logic with capability/implementation logic **Fix Required** 1. Rename to contract terminology: - `CapabilityRegistry` → `ContractRegistry` - `CapabilityRecord` → `ContractRecord` - `CapabilityLoader` → `ContractLoader` - `capabilities/_muscle/` → `contracts/_muscle/` 2. Clarify in documentation: - template.yaml = contract template (interface) - capability = skill bundle attached to worker (implementation) 3. Separate concerns: - Contract defines what (input/output expectations) - Capability defines how (which skills worker uses) ## References - Issue #114 - Capabilities as skill bundles discussion - Issue #115 - Factories are workers discussion - Issue #116 - Worker handoff mechanism - AGENTS.md - Needs terminology correction - runtime/capability_registry.py - Should be runtime/contract_registry.py - runtime/capability_loader.py - Should be runtime/contract_loader.py

Mark commented

2026-04-10 22:05:31 +00:00

Author

Owner

Code Evidence: Workers Have "Capabilities" (Should Be "Contracts")

runtime/worker_registry.py:180-289

Workers register with "capabilities" but this is terminology confusion:

# Line 196-204: Validates "capabilities" against registry
valid_caps = []
for cap in capabilities:
    if self.capability_registry.get(cap):  # ← Should be contract_registry
        valid_caps.append(cap)

# Line 250: Stores "capabilities" in worker record
(worker_id, tailnet_address, node_id, capabilities, skills, ...)

# Line 281-282: Queues "capability verification"
for cap in valid_caps:
    self._queue_verification(worker_id, cap)

The Confusion

Workers are registering "capabilities" but what they're actually registering is:

Which contracts they can execute (contract_id)
Which skills they have loaded (skill_id)

What Should Happen

Workers register:

# Worker has contracts (can execute) + skills (implementation)
WorkerRegistration:
  worker_id: str
  contracts: set[str]  # Which contract types they can handle
  skills: set[str]    # Which skills they have loaded
  behavior_contract: str  # Worker behavior strategy (e.g., aggressive_claimer_v1)

Current "Capability" Fields Are Actually Contract References

Evidence from WorkerRegistration (line 40-63):

capabilities: set[str] - Should be contracts: set[str]
behavior_capability: str - Should be behavior_contract: str
Validation against capability_registry.get(cap) - Should validate against contract templates

Ledger Schema Also Confused

From substrate/ledger.py:

capability_id TEXT DEFAULT '' in agents table
capability_id TEXT NOT NULL in worker_instances table

These should be contract_id - they reference which contract the worker is executing.

Impact

The terminology confusion causes:

Workers think they ARE capabilities (identity confusion)
Infrastructure validates contracts as if they're worker attributes
No clear separation between:
- Contract (interface definition)
- Capability (skill bundle attached to worker)
- Worker (execution context)

References

runtime/worker_registry.py:180-289 - Worker registration with "capabilities"
runtime/worker_registry.py:40-63 - WorkerRegistration dataclass
substrate/ledger.py - capability_id fields throughout
Issue #117 - Terminology root cause

## Code Evidence: Workers Have "Capabilities" (Should Be "Contracts") **runtime/worker_registry.py:180-289** Workers register with "capabilities" but this is terminology confusion: ```python # Line 196-204: Validates "capabilities" against registry valid_caps = [] for cap in capabilities: if self.capability_registry.get(cap): # ← Should be contract_registry valid_caps.append(cap) # Line 250: Stores "capabilities" in worker record (worker_id, tailnet_address, node_id, capabilities, skills, ...) # Line 281-282: Queues "capability verification" for cap in valid_caps: self._queue_verification(worker_id, cap) ``` **The Confusion** Workers are registering "capabilities" but what they're actually registering is: - **Which contracts they can execute** (contract_id) - **Which skills they have loaded** (skill_id) **What Should Happen** Workers register: ```python # Worker has contracts (can execute) + skills (implementation) WorkerRegistration: worker_id: str contracts: set[str] # Which contract types they can handle skills: set[str] # Which skills they have loaded behavior_contract: str # Worker behavior strategy (e.g., aggressive_claimer_v1) ``` **Current "Capability" Fields Are Actually Contract References** Evidence from WorkerRegistration (line 40-63): - `capabilities: set[str]` - Should be `contracts: set[str]` - `behavior_capability: str` - Should be `behavior_contract: str` - Validation against `capability_registry.get(cap)` - Should validate against contract templates **Ledger Schema Also Confused** From substrate/ledger.py: - `capability_id TEXT DEFAULT ''` in agents table - `capability_id TEXT NOT NULL` in worker_instances table These should be `contract_id` - they reference which contract the worker is executing. **Impact** The terminology confusion causes: 1. Workers think they ARE capabilities (identity confusion) 2. Infrastructure validates contracts as if they're worker attributes 3. No clear separation between: - Contract (interface definition) - Capability (skill bundle attached to worker) - Worker (execution context) ## References - runtime/worker_registry.py:180-289 - Worker registration with "capabilities" - runtime/worker_registry.py:40-63 - WorkerRegistration dataclass - substrate/ledger.py - capability_id fields throughout - Issue #117 - Terminology root cause

Mark commented

2026-04-10 22:06:02 +00:00

Author

Owner

Template.yaml Structure Evidence

capabilities/_muscle/writer/v1/template.yaml

Current naming (incorrect):

capability:  # ← Should be "contract"
  id: writer  # ← Should be "contract_id"
  class: muscle

skills:  # ← This is correct - defines skill_family for contract
  - type: write_article
    confidence: 0.95

execution:  # ← Contract execution terms
  bond_required: 10
  ttl_seconds: 300

What This Actually Defines

This is a contract template, not a capability template:

id: writer = Contract identifier (which contract type)
skills: = Skill family that can fulfill contract
execution.bond_required = Economic terms
genotype.constraints = Validation constraints

Correct Structure Should Be

contract:  # Contract template definition
  id: writer  # Contract identifier
  class: muscle  # Contract tier
  
  # Interface definition
  input_schema:
    - topic: string (required)
    - format: string (optional)
    - word_count: int (optional)
  output_schema:
    - article_markdown: string (required)
    - word_count: int (actual)
    - citations: list
  
  # Skill binding
  skill_family: writer  # Skills that can fulfill
  skills:
    - type: write_article
      confidence: 0.95
  
  # Economic terms
  bond_required: 10
  reward_pool: 5.0
  timeout_ms: 300000
  
  # Validation constraints
  constraints:
    min_word_count: 800
    citation_required: true

worker_factory Template Also Confused

capabilities/_muscle/worker_factory/template.yaml:

Line 4: capability.id: worker_factory - Should be contract.id: worker_factory
Defines contract for worker provisioning, NOT capability

Directory Naming Confusion

capabilities/_muscle/writer/v1/ should be:

contracts/_muscle/writer/v1/ - Contract templates directory

Workers don't "have" these directories - they reference these contract templates when executing.

Summary

Every file currently called "capability template" is actually a "contract template". The entire naming convention needs systematic renaming:

Directory: capabilities/ → contracts/
Template field: capability: → contract:
Registry: CapabilityRegistry → ContractRegistry
Worker fields: capabilities: → contracts:
Ledger fields: capability_id → contract_id

This is foundational - all downstream architecture depends on this terminology correction.

## Template.yaml Structure Evidence **capabilities/_muscle/writer/v1/template.yaml** Current naming (incorrect): ```yaml capability: # ← Should be "contract" id: writer # ← Should be "contract_id" class: muscle skills: # ← This is correct - defines skill_family for contract - type: write_article confidence: 0.95 execution: # ← Contract execution terms bond_required: 10 ttl_seconds: 300 ``` **What This Actually Defines** This is a **contract template**, not a capability template: - `id: writer` = Contract identifier (which contract type) - `skills:` = Skill family that can fulfill contract - `execution.bond_required` = Economic terms - `genotype.constraints` = Validation constraints **Correct Structure Should Be** ```yaml contract: # Contract template definition id: writer # Contract identifier class: muscle # Contract tier # Interface definition input_schema: - topic: string (required) - format: string (optional) - word_count: int (optional) output_schema: - article_markdown: string (required) - word_count: int (actual) - citations: list # Skill binding skill_family: writer # Skills that can fulfill skills: - type: write_article confidence: 0.95 # Economic terms bond_required: 10 reward_pool: 5.0 timeout_ms: 300000 # Validation constraints constraints: min_word_count: 800 citation_required: true ``` **worker_factory Template Also Confused** `capabilities/_muscle/worker_factory/template.yaml`: - Line 4: `capability.id: worker_factory` - Should be `contract.id: worker_factory` - Defines contract for worker provisioning, NOT capability **Directory Naming Confusion** `capabilities/_muscle/writer/v1/` should be: - `contracts/_muscle/writer/v1/` - Contract templates directory Workers don't "have" these directories - they reference these contract templates when executing. **Summary** Every file currently called "capability template" is actually a "contract template". The entire naming convention needs systematic renaming: 1. Directory: `capabilities/` → `contracts/` 2. Template field: `capability:` → `contract:` 3. Registry: `CapabilityRegistry` → `ContractRegistry` 4. Worker fields: `capabilities:` → `contracts:` 5. Ledger fields: `capability_id` → `contract_id` This is foundational - all downstream architecture depends on this terminology correction.

Mark commented

2026-04-13 01:40:35 +00:00

Author

Owner

RESOLVED - Terminology refactored to "primitives"

This issue has been addressed by the comprehensive terminology refactoring in commit a10e79f.

What was done:

Directory renamed: capabilities/ → primitives/
- Supersedes "contracts" terminology - primitives is the umbrella term
- Includes: workers, factories, skills, tools, prompts, bones, contracts
Runtime modules renamed:
- capability_loader.py → primitive_loader.py
- capability_registry.py → primitive_registry.py
- capability_watcher.py → primitive_watcher.py
- capability_validator.py → primitive_validator.py
- capability_execution.py → primitive_execution.py
Class names updated:
- CapabilityRegistry → PrimitiveRegistry
- CapabilityLoader → PrimitiveLoader
- CapabilityRecord → PrimitiveRecord (now has type and tier fields)
Template schema updated:
- All template.yaml files have primitive:, type:, and tier: fields
- Types: worker, factory, skill, tool, prompt, bone, contract
- Tiers: muscle (stable), nerve (experimental), bone (fast-path)
Base templates created:
- primitives/_shared/base_templates/ with base templates for all types

Why "primitives" over "contracts":

"Primitives" is more accurate - these are mesh building blocks
"Contracts" was just one type (intent-binding interfaces)
The hierarchy is now: primitives → types → tiers

Tests: All 43 tests passing, 24/25 primitives loading correctly.

This issue can be closed.

**RESOLVED - Terminology refactored to "primitives"** This issue has been addressed by the comprehensive terminology refactoring in commit a10e79f. **What was done:** 1. **Directory renamed:** `capabilities/` → `primitives/` - Supersedes "contracts" terminology - primitives is the umbrella term - Includes: workers, factories, skills, tools, prompts, bones, contracts 2. **Runtime modules renamed:** - capability_loader.py → primitive_loader.py - capability_registry.py → primitive_registry.py - capability_watcher.py → primitive_watcher.py - capability_validator.py → primitive_validator.py - capability_execution.py → primitive_execution.py 3. **Class names updated:** - CapabilityRegistry → PrimitiveRegistry - CapabilityLoader → PrimitiveLoader - CapabilityRecord → PrimitiveRecord (now has type and tier fields) 4. **Template schema updated:** - All template.yaml files have `primitive:`, `type:`, and `tier:` fields - Types: worker, factory, skill, tool, prompt, bone, contract - Tiers: muscle (stable), nerve (experimental), bone (fast-path) 5. **Base templates created:** - primitives/_shared/base_templates/ with base templates for all types **Why "primitives" over "contracts":** - "Primitives" is more accurate - these are mesh building blocks - "Contracts" was just one type (intent-binding interfaces) - The hierarchy is now: primitives → types → tiers **Tests:** All 43 tests passing, 24/25 primitives loading correctly. This issue can be closed.