OneCAD-Draft/crates/ocs_doc_api/spec/entities.toml

# Curated source of truth for ocs_doc_api codegen (plan §10, decision #6).
# Maps entity families + their construction ops, geometric actions, and queries
# to kernel fns / acadrust variants. build.rs regenerates src/gen/* from this;
# CI fails on drift. New op/query variants append at the END only (bincode
# discriminant stability).
#
# `status` values: "supported" (default), "unsupported" (present but errors),
# "planned" (roadmap; no callable surface). Generic handle methods
# (bounds/transform/delete) are documented once in build.rs and apply to every
# family unless overridden here.

[meta]
envelope_version = 1

# ============================================================================
# SOLID FAMILY (phase 1) — B-rep solids via cadkernel
# ============================================================================
[[family]]
name = "Solid"
acadrust_variant = "Solid3D"
handle = "Solid"
collection = "solids"
description = "B-rep solid. Host resolves bodies via the solid_models cache (lift-on-miss from ACIS SAT)."

[[family.constructor]]
name = "create_cuboid"
args = [{ name = "origin", ty = "[f64; 3]" }, { name = "size", ty = "[f64; 3]" }]
op = "CreateSolid"
fixed = { primitive = "Cuboid" }

[[family.constructor]]
name = "create_sphere"
args = [{ name = "centre", ty = "[f64; 3]" }, { name = "radius", ty = "f64" }]
op = "CreateSolid"
fixed = { primitive = "Sphere" }

[[family.constructor]]
name = "create_cylinder"
args = [{ name = "base", ty = "[f64; 3]" }, { name = "radius", ty = "f64" }, { name = "height", ty = "f64" }]
op = "CreateSolid"
fixed = { primitive = "Cylinder" }

[[family.constructor]]
name = "create_cone"
args = [{ name = "base", ty = "[f64; 3]" }, { name = "radius", ty = "f64" }, { name = "height", ty = "f64" }]
op = "CreateSolid"
fixed = { primitive = "Cone" }

[[family.constructor]]
name = "create_torus"
args = [{ name = "centre", ty = "[f64; 3]" }, { name = "major_radius", ty = "f64" }, { name = "minor_radius", ty = "f64" }]
op = "CreateSolid"
fixed = { primitive = "Torus" }

[[family.constructor]]
name = "create_wedge"
args = [{ name = "origin", ty = "[f64; 3]" }, { name = "size", ty = "[f64; 3]" }]
op = "CreateSolid"
fixed = { primitive = "Wedge" }

[[family.constructor]]
name = "extrude"
args = [{ name = "profile", ty = "EntityRef" }, { name = "direction", ty = "[f64; 3]" }]
op = "Extrude"

[[family.constructor]]
name = "revolve"
args = [{ name = "profile", ty = "EntityRef" }, { name = "pivot", ty = "[f64; 3]" }, { name = "axis", ty = "[f64; 3]" }, { name = "angle", ty = "f64" }]
op = "Revolve"

[[family.method]]
name = "intersect"
kind = "op"
op = "SolidBoolean"
args = [{ name = "other", ty = "Solid" }]
returns = "Solid"
fixed = { op = "Intersection", erase_sources = true }

[[family.method]]
name = "union"
kind = "op"
op = "SolidBoolean"
args = [{ name = "other", ty = "Solid" }]
returns = "Solid"
fixed = { op = "Union", erase_sources = true }

[[family.method]]
name = "subtract"
kind = "op"
op = "SolidBoolean"
args = [{ name = "other", ty = "Solid" }]
returns = "Solid"
fixed = { op = "Difference", erase_sources = true }

[[family.method]]
name = "volume"
kind = "query"
query = "GetVolume"
returns = "f64"

[[family.method]]
name = "centroid"
kind = "query"
query = "GetCentroid"
returns = "[f64; 3]"

[[family.method]]
name = "intersects"
kind = "query"
query = "GetIntersects"
args = [{ name = "other", ty = "Solid" }]
returns = "bool"

# ============================================================================
# CURVE FAMILY (phase 1, minimal 2D)
# ============================================================================
[[family]]
name = "Line"
acadrust_variant = "Line"
handle = "Line"
collection = "curves"

[[family.constructor]]
name = "create_line"
args = [{ name = "start", ty = "[f64; 3]" }, { name = "end", ty = "[f64; 3]" }]
op = "CreateCurve"
fixed = { curve = "Line" }

[[family]]
name = "Circle"
acadrust_variant = "Circle"
handle = "Circle"
collection = "curves"

[[family.constructor]]
name = "create_circle"
args = [{ name = "centre", ty = "[f64; 3]" }, { name = "radius", ty = "f64" }]
op = "CreateCurve"
fixed = { curve = "Circle" }

[[family]]
name = "Polyline"
acadrust_variant = "LwPolyline"
handle = "Polyline"
collection = "curves"

[[family.constructor]]
name = "create_polyline"
args = [{ name = "points", ty = "&[[f64; 3]]" }, { name = "closed", ty = "bool" }]
op = "CreateCurve"
fixed = { curve = "Polyline" }

[[family.method]]
name = "add_vertex"
kind = "op"
op = "AddVertex"
args = [{ name = "at", ty = "usize" }, { name = "point", ty = "[f64; 3]" }]
returns = "()"

[[family]]
name = "Point"
acadrust_variant = "Point"
handle = "Point"
collection = "curves"

[[family.constructor]]
name = "create_point"
args = [{ name = "position", ty = "[f64; 3]" }]
op = "CreateCurve"
fixed = { curve = "Point" }

[[family.constructor]]
name = "create_points"
args = [{ name = "positions", ty = "&[[f64; 3]]" }]
op = "CreateMany"
fixed = { curve = "Point" }
bulk = true
returns = "Vec<Point>"

[[family]]
name = "Arc"
acadrust_variant = "Arc"
handle = "ArcCurve"
collection = "curves"

[[family.constructor]]
name = "create_arc"
args = [{ name = "centre", ty = "[f64; 3]" }, { name = "radius", ty = "f64" }, { name = "start_angle", ty = "f64" }, { name = "end_angle", ty = "f64" }]
op = "CreateCurve"
fixed = { curve = "Arc" }

[[family]]
name = "Ellipse"
acadrust_variant = "Ellipse"
handle = "Ellipse"
collection = "curves"

[[family.constructor]]
name = "create_ellipse"
args = [{ name = "centre", ty = "[f64; 3]" }, { name = "major_axis", ty = "[f64; 3]" }, { name = "ratio", ty = "f64" }, { name = "start", ty = "f64" }, { name = "end", ty = "f64" }]
op = "CreateCurve"
fixed = { curve = "Ellipse" }

[[family]]
name = "Spline"
acadrust_variant = "Spline"
handle = "Spline"
collection = "curves"

[[family.constructor]]
name = "create_spline"
args = [{ name = "degree", ty = "i32" }, { name = "control_points", ty = "&[[f64; 3]]" }, { name = "knots", ty = "&[f64]" }, { name = "weights", ty = "&[f64]" }]
op = "CreateCurve"
fixed = { curve = "Spline" }

[[family]]
name = "Ray"
acadrust_variant = "Ray"
handle = "Ray"
collection = "curves"

[[family.constructor]]
name = "create_ray"
args = [{ name = "origin", ty = "[f64; 3]" }, { name = "direction", ty = "[f64; 3]" }]
op = "CreateCurve"
fixed = { curve = "Ray" }

[[family]]
name = "XLine"
acadrust_variant = "XLine"
handle = "XLine"
collection = "curves"

[[family.constructor]]
name = "create_xline"
args = [{ name = "origin", ty = "[f64; 3]" }, { name = "direction", ty = "[f64; 3]" }]
op = "CreateCurve"
fixed = { curve = "XLine" }

# ============================================================================
# ANNOTATION FAMILY (phase 2b) — text annotations
# ============================================================================
[[family]]
name = "Text"
acadrust_variant = "Text"
handle = "Text"
collection = "curves"
description = "Single-line text annotation. content()/set_content() read+replace the value; transform moves insertion point."

[[family.constructor]]
name = "create_text"
args = [{ name = "value", ty = "&str" }, { name = "insertion_point", ty = "[f64; 3]" }, { name = "height", ty = "f64" }, { name = "rotation", ty = "f64" }]
op = "CreateText"

[[family.method]]
name = "content"
kind = "query"
query = "GetTextContent"
returns = "String"

[[family.method]]
name = "set_content"
kind = "op"
op = "SetTextContent"
args = [{ name = "value", ty = "&str" }]
returns = "()"

[[family]]
name = "MText"
acadrust_variant = "MText"
handle = "MText"
collection = "curves"
description = "Multi-line text annotation. content()/set_content() read+replace the value; transform moves insertion point."

[[family.constructor]]
name = "create_mtext"
args = [{ name = "value", ty = "&str" }, { name = "insertion_point", ty = "[f64; 3]" }, { name = "height", ty = "f64" }]
op = "CreateMText"

[[family.method]]
name = "content"
kind = "query"
query = "GetTextContent"
returns = "String"

[[family.method]]
name = "set_content"
kind = "op"
op = "SetTextContent"
args = [{ name = "value", ty = "&str" }]
returns = "()"

# ============================================================================
# HATCH FAMILY (phase 2b) — filled regions
# ============================================================================
[[family]]
name = "Hatch"
acadrust_variant = "Hatch"
handle = "Entity"
collection = "curves"
description = "Filled region over a closed polyline boundary. boundary() returns the loops; bounds from boundary; generic delete."

[[family.constructor]]
name = "create_hatch"
args = [{ name = "boundary", ty = "&[[f64; 2]]" }, { name = "solid", ty = "bool" }]
op = "CreateHatch"

[[family.method]]
name = "boundary"
kind = "query"
query = "GetHatchBoundary"
returns = "Vec<Vec<[f64; 2]>>"

# ============================================================================
# DIMENSION FAMILY (phase 2c) — linear dimensions
# ============================================================================
[[family]]
name = "Dimension"
acadrust_variant = "Dimension"
handle = "Dimension"
collection = "curves"
description = "Linear dimension between two measured points. measurement() reads the distance; bounds from the measured + definition points."

[[family.constructor]]
name = "create_dimension_linear"
args = [{ name = "first_point", ty = "[f64; 3]" }, { name = "second_point", ty = "[f64; 3]" }, { name = "definition_point", ty = "[f64; 3]" }]
op = "CreateDimensionLinear"

[[family.method]]
name = "measurement"
kind = "query"
query = "GetDimensionMeasurement"
returns = "f64"

# ============================================================================
# CONTAINER FAMILY (phase 3) — block references
# ============================================================================
[[family]]
name = "Insert"
acadrust_variant = "Insert"
handle = "Entity"
collection = "entities"
description = "Block reference. Place an existing BlockRecord by name; transform moves its insert point."

[[family.constructor]]
name = "create_insert"
args = [{ name = "block_name", ty = "&str" }, { name = "insert_point", ty = "[f64; 3]" }, { name = "scale", ty = "f64" }, { name = "rotation", ty = "f64" }]
op = "CreateInsert"

# ============================================================================
# PAPER-SPACE FAMILY (phase 4) — viewports
# ============================================================================
[[family]]
name = "Viewport"
acadrust_variant = "Viewport"
handle = "Entity"
collection = "entities"
description = "Paper-space viewport: a width×height window at center looking at view_target with view_height zoom. bounds = center ± w/2,h/2; transform moves center."

[[family.constructor]]
name = "create_viewport"
args = [{ name = "center", ty = "[f64; 3]" }, { name = "width", ty = "f64" }, { name = "height", ty = "f64" }, { name = "view_target", ty = "[f64; 3]" }, { name = "view_height", ty = "f64" }]
op = "CreateViewport"

# ============================================================================
# MEDIA & MISC (phase 5, read-mostly) — read-only EntityView, no typed create.
# These families report a real `kind` via GetEntity and coarse bounds where
# computable; they have no typed construction/geometric ops in v1.
# ============================================================================
[[family]]
name = "RasterImage"
acadrust_variant = "RasterImage"
handle = "Entity"
collection = "entities"
description = "Raster image (read-mostly): GetEntity kind + coarse bounds (insertion + u*width + v*height); generic delete. No typed create in v1."

[[family]]
name = "Table"
acadrust_variant = "Table"
handle = "Entity"
collection = "entities"
description = "Table (read-only): GetEntity kind; generic delete. No typed create/bounds in v1."

# ============================================================================
# Cross-cutting ops (generic handles + bulk) — documented in build.rs
# ============================================================================
# - Generic handle methods on EVERY handle: bounds() -> Aabb, transform(placement),
#   delete(), id() -> ObjectId. (transform is solids-only in v1.)
# - EntityCollection: get(id) -> Entity, delete(id), transform_many(&ids, pl),
#   delete_many(&ids).
# - Bulk ops (CreateMany / TransformMany / DeleteMany): single op, all-or-nothing
#   via upfront validation, item-capped (BULK_ITEM_CAP).
# - Read-only batching: query_batch(|q| ...) — one round-trip, no revision bump.
# - OpGroup: best-effort client-side failure cleanup (NOT a transaction).

# ---- Kernel/op mapping (reference for the executor + docs) ----
[[kernel_map]]
op = "CreateSolid.Cuboid"
kernel = "cadkernel::brep::make::cuboid"
returns = "Option<Body>"

[[kernel_map]]
op = "CreateSolid.Sphere"
kernel = "cadkernel::brep::make::sphere"
returns = "Option<Body>"

[[kernel_map]]
op = "SolidBoolean"
kernel = "cadkernel::brep::combine"
returns = "Result<Body, Snag>"

[[kernel_map]]
op = "Transform"
kernel = "cadkernel::brep::transform"
returns = "Option<Body>"

[[kernel_map]]
op = "GetBounds"
kernel = "cadkernel::brep::body_bounds"
returns = "Option<Aabb>"

[[kernel_map]]
op = "GetVolume"
kernel = "cadkernel::brep::mesh_body + divergence"
returns = "computed"