@snaptrude/plugin-core 0.0.0-dev-20260911064951 → 0.0.0-surfaces-20260921090636

package/src/api/design/index.ts

@@ -14,7 +14,6 @@ import { PluginDesignTransformApi } from "./transform"
 import { PluginDesignEditApi } from "./edit"
 import { PluginDesignUpdateApi } from "./update"
 import { PluginDesignVisibilityApi } from "./visibility"
-import { PluginDesignDimensionsApi } from "./dimensions"
 import { PluginDesignTypesApi } from "./types"
 import { PluginDesignFamilyApi } from "./family"
 import { PluginDesignChangeResult } from "./lock"
@@ -32,7 +31,6 @@ import { PluginDesignChangeResult } from "./lock"
  * - {@linkcode PluginDesignApi.erase} — plan-level adjacency-edge erase (NOT hard delete)
  * - {@linkcode PluginDesignApi.delete} — hard entity removal
  * - {@linkcode PluginDesignApi.visibility} — hide / isolate / reveal entities
- * - {@linkcode PluginDesignApi.dimensions} — dimension lines (Measuring Tape): create / list / delete / hide
  * - {@linkcode PluginDesignApi.types} — read-only building type / assembly reference
  * - {@linkcode PluginDesignApi.family} — author parametric families from a JSON spec
  * - {@linkcode PluginDesignApi.lock} / {@linkcode PluginDesignApi.unlock} / {@linkcode PluginDesignApi.isLocked} / {@linkcode PluginDesignApi.listLocked} — lock state (top-level design verbs, §2A.1)
@@ -69,8 +67,6 @@ export abstract class PluginDesignApi {
   public abstract update: PluginDesignUpdateApi
   /** Hide / isolate / reveal entities. See {@linkcode PluginDesignVisibilityApi}. */
   public abstract visibility: PluginDesignVisibilityApi
-  /** Dimension lines (Measuring Tape). See {@linkcode PluginDesignDimensionsApi}. */
-  public abstract dimensions: PluginDesignDimensionsApi
   /** Read-only building type / assembly reference. See {@linkcode PluginDesignTypesApi}. */
   public abstract types: PluginDesignTypesApi
   /** Author parametric families from a JSON spec. See {@linkcode PluginDesignFamilyApi}. */
@@ -264,6 +260,5 @@ export * from "./transform"
 export * from "./edit"
 export * from "./update"
 export * from "./visibility"
-export * from "./dimensions"
 export * from "./types"
 export * from "./family"

package/src/api/design/query/geometry/index.ts

@@ -34,10 +34,25 @@ export abstract class PluginDesignQueryGeometryApi {
    * scene entity, as a reusable {@linkcode BrepHandle} for the
    * `core.geom.query.brep.*` reads.
    *
+   * **Frame.** By default the brep comes back in the component's own LOCAL frame
+   * (its vertices are relative to the mesh origin, exactly as stored) — the
+   * behaviour every 0.9.x caller relies on. Pass `{ frame: "world" }` to get the
+   * same solid placed where it sits in the scene (world coordinates, like
+   * `getBottomContour` / `getTriangulatedMeshes` and every `design.query.measure`
+   * read). Use `"world"` whenever the handle will be COMBINED with other scene
+   * geometry or committed back beside its source: booleans between two scene
+   * masses, `brepFromFillet` / `brepFromShell` / `brepFromOffset` /
+   * `brepFromChamfer` on a scene mass followed by `massFromBrep`, or comparing
+   * its vertices with a bounding box. A world-frame handle from a parametrically
+   * live mass also carries that mass's recipe, so an operation result keeps an
+   * editable record.
+   *
    * @param component - The scene component to read
+   * @param options - `frame`: `"local"` (default, mesh-local coordinates) or `"world"` (scene coordinates)
    * @returns The brep as a {@linkcode BrepHandle}, or `null` if the component has no brep geometry
    *
    * @examplePrompt Get the 3D solid geometry of the selected wall
+   * @examplePrompt Round the top rim of this column and put it back where it is
    * @examplePrompt How many faces does this mass have?
    * @examplePrompt Inspect the mesh of this slab so I can look at its faces and edges
    * @examplePrompt Read the vertices of the selected column's geometry
@@ -48,10 +63,16 @@ export abstract class PluginDesignQueryGeometryApi {
    * if (brep) {
    *   const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
    * }
+   *
+   * // Operate on a scene mass and commit the result where the mass sits:
+   * const placed = await snaptrude.design.query.geometry.getBrep(mass, { frame: "world" })
+   * const rounded = await snaptrude.core.geom.create.brepFromFillet(placed, edges, 0.2)
+   * await snaptrude.design.create.massFromBrep(rounded, "Rounded")
    * ```
    */
   public abstract getBrep(
     component: ComponentHandle,
+    options?: PluginDesignQueryGeometryGetBrepOptions,
   ): PluginApiReturn<BrepHandle | null>
 
   /**
@@ -189,8 +210,16 @@ export abstract class PluginDesignQueryGeometryApi {
  * |---|---|---|
  * | `component` | {@linkcode ComponentHandle} | The scene component to read |
  */
+/** Options for {@linkcode PluginDesignQueryGeometryApi.getBrep}: `frame` defaults to `"local"`. */
+export type PluginDesignQueryGeometryGetBrepOptions = { frame?: "local" | "world" }
+export const PluginDesignQueryGeometryGetBrepOptions: z.ZodType<
+  PluginDesignQueryGeometryGetBrepOptions,
+  PluginDesignQueryGeometryGetBrepOptions
+> = z.object({ frame: z.enum(["local", "world"]).optional() })
+
 export const PluginDesignQueryGeometryGetBrepArgs = z.object({
   component: ComponentHandle,
+  options: PluginDesignQueryGeometryGetBrepOptions.optional(),
 })
 
 export type PluginDesignQueryGeometryGetBrepArgs = z.infer<

package/src/api/design/query/index.ts

@@ -1,6 +1,7 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
 import { ComponentHandle, BBoxComponents } from "../../../handles"
+import type { MassParametersRecord } from "../../../massParameters"
 import {
   PluginSpaceType,
   PluginMassType,
@@ -1014,6 +1015,55 @@ export abstract class PluginDesignQueryApi {
     staircase: ComponentHandle,
   ): PluginApiReturn<PluginStaircaseParams | null>
 
+  /**
+   * Read a mass's creation-parameter record — the recipe it was built from
+   * (`kind` plus the values that constructor was called with). Present on
+   * masses committed from a `core.geom.create` brep constructor that carries a
+   * recipe: {@linkcode MassParametersRecord} covers the four primitives
+   * (sphere, cylinder, cone, torus), extrusions, revolutions, lofts and sweeps.
+   *
+   * A fillet, chamfer, shell or offset of a recorded solid keeps the record
+   * too: `kind` stays the base constructor and the operation is appended to the
+   * record's `operations` list. Edit any of it with `design.update.parameters`.
+   *
+   * `null` for everything else — drawn masses, imported geometry, booleans,
+   * split parts, `brepFromFaces` / `brepFromMesh`, and results built on a
+   * source that carried no record — and for a mass whose record no longer
+   * matches what is on
+   * screen (a later free-form edit dropped the recipe, or the mass carries a
+   * baked scale). `null` too when the recipe was not recordable: the record
+   * schema has its own caps (a sweep path of at most 512 points, a loft of at
+   * most 32 sections, at most 8 chained `operations`, at most 256 curves in one
+   * profile loop and 64 holes in one contour), and a mass built past one of
+   * them — through a route that does not enforce the matching creator cap —
+   * commits as ordinary geometry carrying no record. The `operations` cap is
+   * the one an agent can walk into by accident: a 9th chained
+   * fillet/chamfer/shell/offset drops the record silently, so the result
+   * commits as ordinary geometry and reads back `null` here. A record is never
+   * reported unless it is still the truth.
+   *
+   * Points and axes come back in **world** coordinates. Pure read — nothing is
+   * created or modified.
+   *
+   * @param component - the mass's {@linkcode ComponentHandle}
+   * @returns the {@linkcode MassParametersRecord}, or `null`
+   *
+   * @examplePrompt What radius is this sphere?
+   * @examplePrompt Is this mass parametric?
+   * @examplePrompt Read back the dome's creation parameters
+   * @examplePrompt How tall was this cylinder made?
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses({ isSelected: true })
+   * const params = await snaptrude.design.query.getParameters(mass)
+   * if (params?.kind === "sphere") console.log("radius:", params.values.radius)
+   * ```
+   */
+  public abstract getParameters(
+    component: ComponentHandle,
+  ): PluginApiReturn<MassParametersRecord | null>
+
   /**
    * Get the **union** axis-aligned bounding box enclosing a set of entities.
    *

package/src/api/design/update/index.ts

@@ -9,6 +9,7 @@ import {
   PluginSpaceUpdateResult,
 } from "../../entity/space"
 import { PluginDesignChangeResult } from "../lock"
+import { MassParametersPatch, type MassParametersRecord } from "../../../massParameters"
 import {
   PluginBuildableEnvelopePolygonVertex,
   PluginBuildableEnvelopeSetbackTier,
@@ -136,6 +137,22 @@ export type PluginDesignUpdateStaircaseArgs = z.infer<
   typeof PluginDesignUpdateStaircaseArgs
 >
 
+/**
+ * Arguments for {@linkcode PluginDesignUpdateApi.parameters}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | The parametric mass to edit |
+ * | `patch` | {@linkcode MassParametersPatch} | Partial `values` (+ optional `operations`), or the full edited record |
+ */
+export const PluginDesignUpdateParametersArgs = z.object({
+  component: ComponentHandle,
+  patch: MassParametersPatch,
+})
+export type PluginDesignUpdateParametersArgs = z.infer<
+  typeof PluginDesignUpdateParametersArgs
+>
+
 /**
  * Sparse edits for a wall (all optional; at least one required). Only the
  * fields you provide change. Dimensions are in **engine units** (the same
@@ -409,6 +426,83 @@ export abstract class PluginDesignUpdateApi {
     params: PluginStaircaseParamUpdates,
   ): PluginApiReturn<PluginDesignChangeResult>
 
+  /**
+   * Edit a parametric mass by patching its creation recipe and rebuilding the
+   * solid in place — the mass keeps its id, storey, materials, position and
+   * linked copies; only the geometry changes. Read the current record with
+   * `design.query.getParameters` first.
+   *
+   * `patch` is a partial of `record.values` — or the whole record you read
+   * back, edited. A key you leave out is unchanged (that includes
+   * `operations`). Scalars and points MERGE by key (`{ radius: 8 }` changes
+   * only the radius); arrays (`contour`, `sections`, `path`, `profile`,
+   * `operations`) REPLACE WHOLE when present — send the complete new list;
+   * `{ operations: [] }` drops every operation. A patch that changes nothing
+   * returns the current record and records no edit (no undo step). `kind` and
+   * `version` are immutable: to change the kind, build a new mass. Keys are the
+   * record's `values` keys for its `kind` (sphere: `centre`, `radius`;
+   * cylinder: `base`, `axis`, `radius`, `height`; torus: `centre`, `axis`,
+   * `majorRadius`, `minorRadius`; …) plus `operations`. To change a fillet
+   * radius, edit `operations[i].radius` in the record you read and send
+   * `{ operations }` back. Points and axes are WORLD coordinates in internal
+   * units, exactly as `getParameters` reports them.
+   *
+   * Rebuilds in memory first, then swaps onto the SAME component; every linked
+   * copy regenerates together. One undo step; saves and syncs to collaborators
+   * like any geometry edit. Kernel kinds (revolution, sweep, loft, primitives,
+   * any `operations`) run on OpenCascade — expect a short pause.
+   *
+   * @param component - a mass whose `getParameters` is non-null
+   * @param patch - partial `values` (+ optional `operations`), or the full edited record
+   * @returns the complete post-edit record, world coordinates (what
+   *   `getParameters` now returns)
+   * @throws PRECONDITION_FAILED when the mass carries no live recipe — built
+   *   from a boolean, split, `brepFromFaces`/`brepFromMesh` or drawn; edited
+   *   free-form since (push/pull, move face, boolean); or scaled with the
+   *   transform tool. `getParameters` returns `null` for exactly these.
+   *   Do not retry — rebuild it with a recipe constructor and say so.
+   *   Also PRECONDITION_FAILED when the mass is **locked** (the message says
+   *   so). Locking is invisible to `getParameters` — a locked parametric mass
+   *   still reads back a full record — so this is the one PRECONDITION_FAILED
+   *   the read cannot predict. Unlock the mass and call again; never rebuild
+   *   it, the recipe is intact.
+   *   Also PRECONDITION_FAILED when an `operations` entry's edge/face selectors
+   *   no longer resolve on the rebuilt base (the message names the operation
+   *   and edge): re-select the edges on the new shape and re-apply that
+   *   operation.
+   * @throws VALIDATION for a key the kind does not have (the message lists the
+   *   kind's keys), `kind` or `version` in a partial patch, or a value outside
+   *   the constructor's own rules (torus tube ≥ ring, revolution angle ∉
+   *   (0, 360], a profile crossing its axis, a spline with fewer than
+   *   degree + 1 poles).
+   * @throws OPERATION_FAILED when the kernel cannot build the edited recipe;
+   *   the model is left unchanged.
+   *
+   * @examplePrompt Make the dome's radius 8 metres
+   * @examplePrompt Raise the podium to 5 m
+   * @examplePrompt Widen the vase — move its profile points 20 cm outward
+   * @examplePrompt Change the fillet on the rounded column to 300 mm
+   *
+   * # Example
+   * ```ts
+   * // { kind: "sphere", values: { centre, radius: 19.685 }, … }
+   * const before = await snaptrude.design.query.getParameters(dome)
+   * const after = await snaptrude.design.update.parameters(dome, { radius: 31.496 }) // 8 m in internal units
+   *
+   * // Fillet radius on a recorded result: read → edit → send the array back
+   * const rec = await snaptrude.design.query.getParameters(column)
+   * const operations = rec?.operations ?? []
+   * if (operations[0]?.op === "fillet") {
+   *   operations[0].radius = 1.181
+   *   await snaptrude.design.update.parameters(column, { operations })
+   * }
+   * ```
+   */
+  public abstract parameters(
+    component: ComponentHandle,
+    patch: MassParametersPatch,
+  ): PluginApiReturn<MassParametersRecord>
+
   /**
    * Edit a **wall** — its thickness and/or height (the same command the
    * properties panel's Thickness/Height fields drive) and/or its **wall type**

package/src/handles.ts

@@ -115,19 +115,6 @@ export type UnderlayHandle = EntityId<"underlay">
  */
 export type TerrainHandle = EntityId<"terrain">
 
-/**
- * A **dimension line** — one measurement annotation left behind by the Measuring
- * Tape tool (NOT a width/height/depth property; see `design.dimensions`).
- * Entity-style: the token IS the raw engine dimension id (`dim_…`), resolved live
- * host-side from the dimension-line registry (`getDimensionLineMap()`) — not via
- * `ComponentUtility.FindComponentById`, which does not index dimension lines (a
- * dimension line is not a Component). No arena, no quota, stable across
- * undo/redo and across reloads (the record persists with the project). Returned
- * by `design.dimensions.create` and consumed by every other
- * `design.dimensions.*` method.
- */
-export type DimensionHandle = EntityId<"dimension">
-
 /**
  * A handle to an **asynchronous import job** (today: a DWG → Forge conversion, which
  * can take minutes). Returned immediately by `core.io.import.dwg`; poll it via
@@ -145,8 +132,16 @@ export type Vec3Handle = Handle<"vec3">
 export type QuatHandle = Handle<"quat">
 export type LineHandle = Handle<"line">
 export type ArcHandle = Handle<"arc">
-/** A curve is a line or an arc — its handle is one of those kinds. */
-export type CurveHandle = LineHandle | ArcHandle
+/**
+ * A NURBS curve value handle (open B-spline curve). Minted by
+ * `core.geom.create.splineFromPoints` / `splineFromControlPoints`, accepted everywhere a
+ * {@linkcode CurveHandle} is (profileFromCurves, query.curve.*).
+ * Closed spline loops never exist as a single handle — a closed run is built
+ * directly as a profile via `core.geom.create.profileFromSplinePoints`.
+ */
+export type SplineHandle = Handle<"spline">
+/** A curve is a line, an arc, or a spline — its handle is one of those kinds. */
+export type CurveHandle = LineHandle | ArcHandle | SplineHandle
 /**
  * A circle value handle. A circle is a CLOSED curve — it deliberately does NOT
  * join {@linkcode CurveHandle} (it has no stable start/end and would break the
@@ -246,23 +241,16 @@ export const ImportJobHandle = z
   .min(1)
   .transform((s) => s as ImportJobHandle)
 
-/**
- * {@linkcode DimensionHandle} is an entity-style handle — the raw `dim_…` engine
- * id, validated only as a non-empty string (no `"<kind>_"` prefix enforcement),
- * resolved live host-side against the dimension-line registry (existence
- * enforced there, as `HANDLE_INVALID`).
- */
-export const DimensionHandle = z
-  .string()
-  .min(1)
-  .transform((s) => s as DimensionHandle)
-
 // Value-kind handle schemas (all-handle model, §11).
 export const Vec3Handle = handleSchema("vec3")
 export const QuatHandle = handleSchema("quat")
 export const LineHandle = handleSchema("line")
 export const ArcHandle = handleSchema("arc")
-export const CurveHandle = z.union([LineHandle, ArcHandle])
+export const SplineHandle = handleSchema("spline")
+// Explicitly typed (rather than inferred): the inferred union type prints its
+// three fully-expanded member schemas into handles.d.ts, which is served to
+// agents whole and has a size budget.
+export const CurveHandle: z.ZodType<CurveHandle> = z.union([LineHandle, ArcHandle, SplineHandle])
 export const CircleHandle = handleSchema("circle")
 
 // BREP topology handle schemas (§2A.2.1). Prefix-shape validation only; existence,

package/src/index.ts

@@ -2,4 +2,6 @@ export * from "./api"
 export * from "./types"
 export * from "./host-utils"
 export * from "./handles"
+export * from "./massParameters"
+export * from "./massParameters.ops"
 export * from "./errors"

package/src/massParameters.ops.ts

@@ -0,0 +1,243 @@
+import * as z from "zod"
+import {
+  ContourRecord,
+  CurveRecord,
+  LoftOptions,
+  MAX_LOFT_SECTIONS,
+  MAX_PATH_CURVES,
+  MAX_SWEEP_PATH_POINTS,
+  SweepAlongCurveRecordOptions,
+  SweepOptions,
+  XYZ,
+} from "./massParameters"
+import type { CurveKind, SurfaceKind } from "./massParameters"
+
+/**
+ * The **operation half** of a mass creation-parameter record: which edge or
+ * face of the recipe's solid a kernel step used, the step itself, and the
+ * values a `design.update.parameters` patch may carry.
+ *
+ * Split out of `massParameters.ts` — same contract, same repos, one module each
+ * so either can be read whole — and re-exported from it and from the package
+ * root, so every import path keeps working.
+ *
+ * Everything here is **pure JSON** by construction, exactly as in
+ * {@linkcode MassParametersRecord}: plain objects, numbers and arrays only, one
+ * `{x, y, z}` point shape, no class instances.
+ */
+
+/** Maximum kernel operations chained onto one recipe. */
+export const MAX_OPERATIONS = 8
+/** Maximum edges one fillet/chamfer operation may select. */
+export const MAX_OPERATION_EDGES = 64
+/** Maximum faces one shell operation may open. */
+export const MAX_OPERATION_FACES = 32
+/** Maximum rows in a variable-fillet radius law. */
+export const MAX_FILLET_LAW_SAMPLES = 32
+
+// `XYZ` and the record schemas below are resolved through `z.lazy`: this module
+// and `massParameters.ts` re-export each other, and this one is evaluated first,
+// so their consts are not yet initialised while these schemas are built. The
+// closures run at parse time, when both modules are live.
+const At: z.ZodType<XYZ, XYZ> = z.lazy(() => XYZ)
+
+/**
+ * Which EDGE of the input solid an operation used: its index in
+ * `core.geom.query.brep.listEdges` order at authoring time, the indices of the
+ * two faces it lies between, and its curve kind. This is topology, not
+ * coordinates — it survives a scalar edit of the base recipe (which moves every
+ * edge) and trips on a reorder or a topology change. Read-only: to blend a
+ * different edge, re-select it on the new shape and re-apply the operation.
+ */
+export type EdgeSelector = {
+  index: number
+  faces: [number, number]
+  curve: CurveKind
+  /** Where the edge sits INSIDE its solid: its midpoint in the record's own
+   *  frame, divided by the solid's bounding-box extent — a ratio per axis,
+   *  never a length, so it survives a scalar edit that scales the whole shape.
+   *  Written only when the discriminators above cannot tell two edges apart. A
+   *  tiebreak, never a coordinate fingerprint: a replay checks it within 0.02 of
+   *  the solid's own box and refuses on a miss — it never searches for a better
+   *  candidate. */
+  at?: XYZ
+}
+
+/**
+ * Which FACE of the input solid an operation used: its index in
+ * `core.geom.query.brep.listFaces` order, its surface kind, and the number of
+ * edges in its outer loop. Read-only, like {@linkcode EdgeSelector}.
+ */
+export type FaceSelector = {
+  index: number
+  kind: SurfaceKind
+  edgeCount: number
+  /** The face's centroid under the same normalisation and the same tiebreak
+   *  rule as {@linkcode EdgeSelector}'s `at` — written only where the
+   *  discriminators above cannot separate two faces, which on a freeform solid
+   *  (every face answers `"spline"`) is the common case. */
+  at?: XYZ
+}
+
+/** The input solid's topology at authoring time — the counts a replay checks first. */
+export type TopologyCounts = { faceCount: number; edgeCount: number }
+
+/**
+ * One kernel operation applied to the base recipe's solid, in order. `input`
+ * pins the topology the operation was authored against, so a base edit that
+ * changes the topology is refused rather than mis-applied.
+ *
+ * Edit one by patching the whole list back:
+ * `design.update.parameters(mass, { operations })`.
+ */
+export type OperationRecord =
+  | {
+      op: "fillet"
+      edges: EdgeSelector[]
+      radius: number
+      /** Radius at the far end of the blend contour, internal length units — a
+       *  linear variable blend from `radius`. One edge, and never with `radii`. */
+      endRadius?: number
+      /** The blend's radius law instead: `position` is normalised arc length
+       *  along the blend contour (a ratio 0..1, never converted), `radius` is
+       *  internal length units. 2..32 rows, strictly increasing `position`.
+       *  One edge, and never with `endRadius`. */
+      radii?: { position: number; radius: number }[]
+      input: TopologyCounts
+    }
+  | { op: "chamfer"; edges: EdgeSelector[]; distance: number; input: TopologyCounts }
+  | { op: "shell"; openFaces: FaceSelector[]; thickness: number; input: TopologyCounts }
+  | { op: "offset"; distance: number; input: TopologyCounts }
+
+/**
+ * One value of a `MassParametersPatch` — whatever a record's `values` key (or
+ * `operations`) may hold. Scalars and points merge by key; every array form
+ * replaces the list whole.
+ */
+export type ParameterPatchValue =
+  | number
+  | XYZ
+  | XYZ[]
+  | ContourRecord
+  | ContourRecord[]
+  | CurveRecord[]
+  | LoftOptions
+  | SweepOptions
+  | SweepAlongCurveRecordOptions
+  | OperationRecord[]
+
+const FaceIndex = z.number().int().nonnegative()
+
+/** See {@linkcode EdgeSelector}. */
+export const EdgeSelector: z.ZodType<EdgeSelector, EdgeSelector> = z.strictObject({
+  index: FaceIndex,
+  faces: z.tuple([FaceIndex, FaceIndex]),
+  curve: z.enum(["line", "arc", "circle", "spline"]),
+  at: At.optional(),
+})
+
+/** See {@linkcode FaceSelector}. */
+export const FaceSelector: z.ZodType<FaceSelector, FaceSelector> = z.strictObject({
+  index: FaceIndex,
+  kind: z.enum(["plane", "cylinder", "cone", "sphere", "torus", "spline"]),
+  edgeCount: z.number().int().positive(),
+  at: At.optional(),
+})
+
+/** See {@linkcode TopologyCounts}. */
+export const TopologyCounts: z.ZodType<TopologyCounts, TopologyCounts> = z.strictObject({
+  faceCount: z.number().int().positive(),
+  edgeCount: z.number().int().positive(),
+})
+
+/** One row of a variable fillet's radius law. See {@linkcode OperationRecord}. */
+const FilletLawRow = z.strictObject({
+  position: z.number().finite().min(0).max(1),
+  radius: z.number().finite().positive(),
+})
+
+/**
+ * See {@linkcode OperationRecord}.
+ *
+ * A variable fillet — `endRadius` or `radii` — names ONE edge: the law is a
+ * property of the blend contour that edge belongs to, and `position` is measured
+ * from that edge's start, so a second edge would have no origin. The two forms
+ * are mutually exclusive and `radii` rows run strictly forward.
+ */
+export const OperationRecord: z.ZodType<OperationRecord, OperationRecord> = z
+  .discriminatedUnion("op", [
+    z.strictObject({
+      op: z.literal("fillet"),
+      edges: z.array(EdgeSelector).min(1).max(MAX_OPERATION_EDGES),
+      radius: z.number().finite().positive(),
+      endRadius: z.number().finite().positive().optional(),
+      radii: z.array(FilletLawRow).min(2).max(MAX_FILLET_LAW_SAMPLES).optional(),
+      input: TopologyCounts,
+    }),
+    z.strictObject({
+      op: z.literal("chamfer"),
+      edges: z.array(EdgeSelector).min(1).max(MAX_OPERATION_EDGES),
+      distance: z.number().finite().positive(),
+      input: TopologyCounts,
+    }),
+    z.strictObject({
+      op: z.literal("shell"),
+      openFaces: z.array(FaceSelector).min(1).max(MAX_OPERATION_FACES),
+      thickness: z.number().finite().positive(),
+      input: TopologyCounts,
+    }),
+    z.strictObject({
+      op: z.literal("offset"),
+      distance: z
+        .number()
+        .finite()
+        .refine((value) => value !== 0, { message: "distance must be non-zero" }),
+      input: TopologyCounts,
+    }),
+  ])
+  .superRefine((operation, ctx) => {
+    if (operation.op !== "fillet") return
+    const { edges, endRadius, radii } = operation
+    if (endRadius === undefined && radii === undefined) return
+    if (endRadius !== undefined && radii !== undefined) {
+      ctx.addIssue({
+        code: "custom",
+        message: "endRadius is mutually exclusive with radii",
+      })
+    }
+    if (edges.length !== 1) {
+      ctx.addIssue({
+        code: "custom",
+        message: "a variable fillet names exactly one edge — the blend contour it runs along",
+      })
+    }
+    if (radii?.some((row, i) => i > 0 && row.position <= radii[i - 1].position)) {
+      ctx.addIssue({
+        code: "custom",
+        message: "radii positions must strictly increase",
+      })
+    }
+  })
+
+/**
+ * One value of a parameter patch. See {@linkcode ParameterPatchValue}.
+ *
+ * Deliberately a CLOSED union of the shapes a record's `values` actually hold —
+ * no `z.unknown()`, nothing recursive: an unrecognised value is a VALIDATION at
+ * the wire, not a silent write of nonsense onto a mass. It only ever widens, so
+ * every value it accepted before it still accepts.
+ */
+export const ParameterPatchValue: z.ZodType<ParameterPatchValue, ParameterPatchValue> = z.lazy(() =>
+  z.union([
+    z.number().finite(),
+    XYZ,
+    z.array(XYZ).max(MAX_SWEEP_PATH_POINTS),
+    ContourRecord,
+    z.array(ContourRecord).max(MAX_LOFT_SECTIONS),
+    z.array(CurveRecord).max(MAX_PATH_CURVES),
+    LoftOptions,
+    SweepOptions,
+    SweepAlongCurveRecordOptions,
+    z.array(OperationRecord).max(MAX_OPERATIONS),
+  ]),
+)