feat(gen-sim): add task contracts and scene authoring boundary

docs/source/api_reference/embodichain/embodichain.gen_sim.task_engine.rst

@@ -0,0 +1,30 @@
+embodichain.gen_sim.task_engine
+================================
+
+Task Engine owns scene-independent task interpretation, normalized semantic
+contracts, and the E1-E9 task ontology. These APIs do not perform scene
+grounding or simulator execution.
+
+Package exports
+---------------
+
+.. automodule:: embodichain.gen_sim.task_engine
+   :members:
+
+Contracts
+---------
+
+.. automodule:: embodichain.gen_sim.task_engine.contracts
+   :members:
+
+Interpretation
+--------------
+
+.. automodule:: embodichain.gen_sim.task_engine.interpretation
+   :members:
+
+Ontology
+--------
+
+.. automodule:: embodichain.gen_sim.task_engine.ontology
+   :members:

docs/source/api_reference/index.rst

@@ -80,3 +80,4 @@ documentation. CI runs this same checker after style checks and before tests.
    :maxdepth: 1
 
    public_api
+   embodichain/embodichain.gen_sim.task_engine

docs/source/api_reference/public_api.rst

@@ -238,6 +238,58 @@ embodichain.gen_sim.scene_engine.core.scene_edit_plan
    SceneEditOperation
    SceneEditPlan
 
+embodichain.gen_sim.scene_engine.errors
+---------------------------------------
+
+.. currentmodule:: embodichain.gen_sim.scene_engine.errors
+
+Scene service failures preserve typed preparation and materialization errors
+across the Task Engine boundary.
+
+.. autosummary::
+
+   SceneServiceError
+
+embodichain.gen_sim.scene_engine.pipeline
+-----------------------------------------
+
+.. currentmodule:: embodichain.gen_sim.scene_engine.pipeline
+
+The public authoring boundary separates deterministic scene analysis from
+side-effecting materialization for generated and edited scenes.
+
+.. autosummary::
+
+   SCENE_BLUEPRINT_SCHEMA
+   SCENE_EDIT_BLUEPRINT_SCHEMA
+   SceneBlueprintPackage
+   SceneEditBlueprintPackage
+   SceneMaterialization
+   analyze_edit
+   analyze_image
+   materialize_blueprint
+   materialize_edit
+
+embodichain.gen_sim.scene_engine.pipeline.api
+---------------------------------------------
+
+.. currentmodule:: embodichain.gen_sim.scene_engine.pipeline.api
+
+Versioned blueprint artifacts and analyze/materialize operations provide the
+implementation-level Scene Engine authoring contract.
+
+.. autosummary::
+
+   SCENE_BLUEPRINT_SCHEMA
+   SCENE_EDIT_BLUEPRINT_SCHEMA
+   SceneBlueprintPackage
+   SceneEditBlueprintPackage
+   SceneMaterialization
+   analyze_edit
+   analyze_image
+   materialize_blueprint
+   materialize_edit
+
 embodichain.gen_sim.scene_engine.pipeline.editing.scene_edit_asset_preparation
 -------------------------------------------------------------------------------
 

embodichain/gen_sim/scene_engine/core/scene_edit_plan.py

@@ -35,7 +35,24 @@
 
 @dataclass(frozen=True)
 class SceneEditOperation:
-    """One normalized edit operation produced from an LLM edit draft."""
+    """Describe one normalized add, move, or delete operation.
+
+    Attributes:
+        op: Operation kind. Add creates a new object, move repositions an
+            existing object, and delete removes an existing object.
+        object_id: Existing object ID for move/delete, or the generated ID for
+            an added object.
+        target_id: Optional existing scene object used as the spatial target.
+        relation: Spatial relation between the edited object and ``target_id``.
+        table_region: Optional named tabletop region. It is valid only when the
+            target is the table and the relation is ``"on"``.
+        category: Semantic category required for an added object.
+        name: Human-readable name required for an added object.
+        description: Generation prompt and semantic description required for
+            an added object.
+        orientation_state: Optional standing or lying intent for an added
+            object. Move operations may only preserve the existing state.
+    """
 
     op: SceneEditOperationType
     object_id: str | None = None
@@ -64,7 +81,22 @@ def to_dict(self) -> dict[str, object]:
 
 @dataclass
 class SceneEditPlan:
-    """Validated operations against one immutable pre-edit scene state."""
+    """Validate edit operations against one pre-edit scene state.
+
+    Construction validates every object reference and rejects conflicting
+    operations without mutating the supplied scene or scene graph.
+
+    Attributes:
+        scene: Scene state that exists before the edit is applied.
+        scene_graph: Pre-edit support and spatial-relation graph. Its node IDs
+            must match the scene object IDs.
+        operations: Normalized operations in application order.
+
+    Raises:
+        ValueError: If scene IDs are inconsistent, an operation has invalid
+            fields or references, edits conflict, or a deletion would orphan a
+            support descendant.
+    """
 
     scene: Scene
     scene_graph: SceneGraph

embodichain/gen_sim/scene_engine/errors.py

@@ -0,0 +1,23 @@
+# ----------------------------------------------------------------------------
+# Copyright (c) 2021-2026 DexForce Technology Co., Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ----------------------------------------------------------------------------
+
+from __future__ import annotations
+
+__all__ = ["SceneServiceError"]
+
+
+class SceneServiceError(RuntimeError):
+    """A transient or remote Scene Engine service failure."""

embodichain/gen_sim/scene_engine/pipeline/__init__.py

@@ -16,4 +16,26 @@
 
 from __future__ import annotations
 
-__all__: list[str] = []
+from .api import (
+    SCENE_BLUEPRINT_SCHEMA,
+    SCENE_EDIT_BLUEPRINT_SCHEMA,
+    SceneBlueprintPackage,
+    SceneEditBlueprintPackage,
+    SceneMaterialization,
+    analyze_edit,
+    analyze_image,
+    materialize_blueprint,
+    materialize_edit,
+)
+
+__all__ = [
+    "SCENE_BLUEPRINT_SCHEMA",
+    "SCENE_EDIT_BLUEPRINT_SCHEMA",
+    "SceneBlueprintPackage",
+    "SceneEditBlueprintPackage",
+    "SceneMaterialization",
+    "analyze_edit",
+    "analyze_image",
+    "materialize_blueprint",
+    "materialize_edit",
+]