feat(sim): add semantic call catalog

[yuecideng]

Description

Stack

• Layer: 6/28
• Base: feat/expert-program-semantic-ir
• Depends on: feat(sim): add declarative scene affordances #489
• Followed by: feat(sim): add semantic integration manifest #491

Add strict typed semantic calls and an explicit call catalog for built-in and registered capabilities. Descriptors own argument schemas, revisions, resource requirements, effect contracts, and exact lowerer identity.

Unknown calls, duplicate registrations, invalid references, and catalog/profile mismatches fail during validation rather than reaching motion execution.

Refs #471
Refs #474

Type of change

• New feature (non-breaking change which adds functionality)

Screenshots

Not applicable.

Validation

• Focused coverage: tests/sim/skills/test_calls.py and test_profiles.py
• Final affected-suite regression on the stack tip: 1215 passed, 2 skipped, 8 deselected
• Changed Python files pass Black 26.3.1; the Sphinx build and rollout-report drift check pass at the stack tip

Checklist

• Changed Python files pass Black 26.3.1.
• Corresponding public/design documentation is included in this stack.
• Tests cover the affected behavior.
• No dependency update is required.

[Copilot]

Pull request overview

Introduces a new immutable “semantic call” layer for sim skills, with a strict typed call catalog that can be validated independently from runtime skill installation. This adds early failure for unknown/invalid semantic calls and prevents stale robot-skill profile bindings after engine skill replacement.

Changes:

• Added embodichain.lab.sim.skills.calls implementing immutable semantic call values (Pick, Place, HandOver, RegisteredSemanticCall), SemanticPose, and an immutable SemanticCallCatalog/SemanticCallDescriptor model.
• Added an AtomicActionEngine.skill_catalog_revision monotonic counter and updated BoundRobotSkillProfile to reject stale bindings based on revision rather than descriptor mapping equality.
• Added focused tests for semantic call payload immutability/validation and for rejecting “equivalent descriptor” implementation replacement on a previously bound profile.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/sim/skills/test_profiles.py	Adds regression test ensuring bound profiles reject “replace=True” engine registrations even when the public descriptor compares equal.
tests/sim/skills/test_calls.py	Adds comprehensive tests covering semantic call value immutability, declarative payload validation, and catalog behavior.
embodichain/lab/sim/skills/profiles.py	Tracks engine catalog revision at bind time; adds engine/source_profile accessors; switches stale detection to revision comparison.
embodichain/lab/sim/skills/calls.py	New semantic call spec + catalog implementation, including declarative argument snapshotting and strict identifier/contract validation.
embodichain/lab/sim/skills/init.py	Exports the new semantic call types and catalog helpers from the skills package.
embodichain/lab/sim/atomic_actions/engine.py	Adds skill_catalog_revision and increments it on semantic-skill registration/replacement to invalidate stale bindings.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[greptile-apps]

Greptile Summary

This PR introduces immutable typed semantic-call values, a catalog for built-in and registered capabilities, and revision-based invalidation of bound skill profiles.

• Adds typed pick, place, hand-over, pose, and registered-extension payloads.
• Adds immutable semantic descriptors, discovery, catalog extension, and built-in catalog construction.
• Tracks semantic skill registrations with a monotonic engine revision and exposes bound-profile ownership.
• Adds focused catalog, payload-validation, and profile-staleness tests.

Confidence Score: 4/5

The PR appears safe to merge from a behavioral perspective, with the non-blocking requirement to document the newly exported semantic-call APIs.

The implementation has focused validation and regression coverage, and no concrete runtime or security defect remains; the accepted concern is that several public APIs are introduced without the repository-required documentation.

Files Needing Attention: embodichain/lab/sim/skills/init.py and the public APIs introduced in calls.py, engine.py, and profiles.py

Important Files Changed

Filename	Overview
embodichain/lab/sim/skills/calls.py	Adds immutable semantic-call payloads, pose snapshots, descriptor validation, and built-in/extension catalog discovery.
embodichain/lab/sim/atomic_actions/engine.py	Adds a monotonic semantic-skill catalog revision incremented when visible bound capabilities are installed or replaced.
embodichain/lab/sim/skills/profiles.py	Uses the engine revision for stale-profile detection and exposes the owning engine and source profile.
embodichain/lab/sim/skills/init.py	Publicly exports the semantic-call catalog API without the documentation required for new public APIs.
tests/sim/skills/test_calls.py	Exercises pose ownership, declarative payload validation, descriptor restrictions, catalog discovery, and built-in mappings.
tests/sim/skills/test_profiles.py	Extends profile tests to cover revision-based invalidation and profile ownership accessors.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Call[SemanticCallSpec] --> Catalog[SemanticCallCatalog]
    Catalog --> Descriptor[SemanticCallDescriptor]
    Descriptor --> Skill[Atomic skill descriptor]
    Engine[AtomicActionEngine] -->|catalog revision| Profile[BoundRobotSkillProfile]
    Profile -->|validates current revision| Skill
    Call -->|resource overrides| Profile

Loading

Prompt To Fix All With AI

### Issue 1
embodichain/lab/sim/skills/__init__.py:21-33
**Document the public semantic API**

The newly exported semantic-call values and catalog APIs, together with the new public engine and profile properties, have no corresponding documentation update. This leaves users without guidance for constructing registered calls, extending catalogs, associating descriptors with installed skills, or handling catalog revisions.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "feat(sim): add semantic call catalog" | Re-trigger Greptile}

[greptile-apps]

Document the public semantic API

The newly exported semantic-call values and catalog APIs, together with the new public engine and profile properties, have no corresponding documentation update. This leaves users without guidance for constructing registered calls, extending catalogs, associating descriptors with installed skills, or handling catalog revisions.

Context Used: CLAUDE.md (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: embodichain/lab/sim/skills/__init__.py
Line: 21-33

Comment:
**Document the public semantic API**

The newly exported semantic-call values and catalog APIs, together with the new public engine and profile properties, have no corresponding documentation update. This leaves users without guidance for constructing registered calls, extending catalogs, associating descriptors with installed skills, or handling catalog revisions.

**Context Used:** CLAUDE.md ([source](https://github.com/dexforce/embodichain/blob/main/CLAUDE.md))

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[yuecideng]

Folded into #492 during stacked-PR consolidation. Its commits remain included in #492; the remote branch is retained for traceability.