@snaptrude/plugin-core 0.9.16 → 0.9.18-edgesetbacks-20261021.1

package/src/massParameters.ts

@@ -1,427 +1,427 @@
-import * as z from "zod"
-import { MAX_OPERATIONS, OperationRecord, ParameterPatchValue } from "./massParameters.ops"
-
-// The selectors, the operation record and the patch-value union live in
-// `massParameters.ops.ts` (split so each module stays small enough for the
-// agent to read in one go) and are re-exported here, so every import path
-// keeps working.
-export * from "./massParameters.ops"
-
-/**
- * Mass **creation-parameter records** — the recipe a parametric mass was built
- * from, shared verbatim by plugin-core, the Snaptrude host, and the agent
- * runtime. There is one schema, not three hand-kept copies.
- *
- * A record is present on a mass committed from a `core.geom.create` brep
- * constructor that carries a recipe (the four primitives, extrusion,
- * revolution, loft, sweep). A fillet, chamfer, shell or offset of a **recorded**
- * solid keeps the record: `kind` stays the base constructor and the step is
- * appended to the record's `operations` list (see {@linkcode OperationRecord}).
- * The record is absent — `null` — for everything
- * else: drawn masses, imported geometry, booleans, split parts,
- * `brepFromFaces`/`brepFromMesh`, and any operation on a solid that carried no
- * record. Geometry there is not a pure function of a legible parameter set, and
- * a record must never be a lie.
- *
- * Read one with `design.query.getParameters`.
- *
- * Everything here is **pure JSON** by construction — plain objects, numbers and
- * arrays only, one `{x, y, z}` point shape everywhere (no tuples, no class
- * instances): records are persisted by enumerable-field reflection, cloned with
- * `structuredClone`, and round-tripped through the collaboration wire.
- */
-
-/** A point in space. The single point shape used across every record. */
-export type XYZ = { x: number; y: number; z: number }
-
-/**
- * One boundary curve of a profile record.
- *
- * The two spline forms are either/or, never both: a curve authored through
- * points carries `splineThrough` (patch the points and the fit re-runs), and a
- * curve with no through-point provenance — read back off an edge, or authored
- * from control vertices — carries `splinePoles` and is re-minted verbatim.
- * There is no variant holding both, so a `throughPoints` edit can never leave
- * stale poles behind.
- */
-export type CurveRecord =
-  | { type: "line"; start: XYZ; end: XYZ }
-  | { type: "arc"; start: XYZ; end: XYZ; centre: XYZ; axis: XYZ }
-  | { type: "circle"; centre: XYZ; axis: XYZ; radius: number }
-  /** Authored via splineFromPoints / profileFromSplinePoints. The through-points
-   *  ARE the recipe; regeneration re-runs the fit version named by
-   *  `fitVersion`. Several chained runs in one contour re-fit as ONE loop; use
-   *  splinePoles to keep their tangents. */
-  | { type: "splineThrough"; fitVersion: 1; throughPoints: XYZ[] }
-  /** No through-points known (authored from control points, or read back off
-   *  an edge). Rebuilt verbatim from these exact poles, knots and
-   *  multiplicities. */
-  | { type: "splinePoles"; degree: number; knots: number[]; mults: number[]; poles: XYZ[] }
-
-/** A closed boundary loop, as an ordered list of curves. */
-export type ProfileRecord = { curves: CurveRecord[] }
-
-/** An outer loop plus its holes — the cross-section shape of a recipe. */
-export type ContourRecord = { outer: ProfileRecord; holes: ProfileRecord[] }
-
-/** Optional loft behaviour switches, mirroring `core.geom.create.brepFromLoft`. */
-export type LoftOptions = {
-  compatibility?: "strict" | "auto"
-  seamAlignment?: "authored" | "auto"
-  /** `"ruled"` (default) keeps the sides straight: every pair of sections
-   *  joined by flat sides. `"smooth"` lofts every section in ONE pass, so the
-   *  sides curve continuously through the intermediates. */
-  smoothing?: "ruled" | "smooth"
-}
-
-/**
- * How a swept profile turns along its path, mirroring
- * `core.geom.create.brepFromSweepAlongCurve`. `"upright"` keeps the profile's up
- * aligned with world up, `"frenet"` lets it roll with the path's curvature, and
- * `"fixed"` carries the authored frame along unchanged.
- */
-export type SweepOrientation = "frenet" | "fixed" | "upright"
-
-/** Optional sweep-along-a-curve switches. Pure JSON: the creator's own bag also
- *  takes a `rail` curve, which is a live handle and never reaches a record. */
-export type SweepAlongCurveRecordOptions = { orientation?: SweepOrientation }
-
-/** Optional sweep scale law and corner transition, mirroring `core.geom.create.brepFromSweep`. */
-export type SweepOptions = {
-  startScale?: number
-  endScale?: number
-  scales?: number[]
-  transition?: "miter" | "round" | { bevel: number }
-}
-
-/** A face's surface kind — the vocabulary of `core.geom.query.face.getSurfaceKind`. */
-export type SurfaceKind = "plane" | "cylinder" | "cone" | "sphere" | "torus" | "spline"
-
-/** An edge's curve kind. Both spline forms of {@linkcode CurveRecord} report `"spline"`. */
-export type CurveKind = "line" | "arc" | "circle" | "spline"
-
-/**
- * A mass's creation recipe: the constructor `kind`, a schema `version`, the
- * `values` that constructor was called with, and the kernel `operations`
- * (fillet / chamfer / shell / offset) applied on top, in order. Points and axes
- * are in the mass's own local frame when stored; `design.query.getParameters`
- * returns them in world coordinates. `operations` is frame-free. One variant
- * per constructor `kind`; its `values` are that constructor's own arguments.
- *
- * `kind` stays the base constructor even after operations: a shelled, filleted
- * sphere is still `{ kind: "sphere", operations: [shell, fillet] }`.
- */
-export type MassParametersRecord =
-  | {
-      kind: "sphere"
-      version: 1
-      values: { centre: XYZ; radius: number }
-      operations?: OperationRecord[]
-    }
-  | {
-      kind: "cylinder"
-      version: 1
-      values: { base: XYZ; axis: XYZ; radius: number; height: number }
-      operations?: OperationRecord[]
-    }
-  | {
-      kind: "cone"
-      version: 1
-      values: { base: XYZ; axis: XYZ; baseRadius: number; topRadius: number; height: number }
-      operations?: OperationRecord[]
-    }
-  | {
-      kind: "torus"
-      version: 1
-      values: { centre: XYZ; axis: XYZ; majorRadius: number; minorRadius: number }
-      operations?: OperationRecord[]
-    }
-  | {
-      kind: "extrusion"
-      version: 1
-      values: {
-        contour: ContourRecord
-        direction: XYZ
-        amount: number
-        /** Total rotation base → top about `direction`, through the base
-         *  contour's centroid, in DEGREES — an angle, never converted. Absent
-         *  or 0 is a straight extrusion. Positive turns the top CLOCKWISE seen
-         *  from the far end of `direction` looking back at the base — for the
-         *  usual upward extrusion, that is the plan view from above. */
-        twistInDegrees?: number
-        /** Top outline scale about the same axis, a ratio — never converted.
-         *  Absent or 1 is a straight extrusion. */
-        topScale?: number
-        /** How many sections the twist/taper was built from, a count (2..64).
-         *  Resolved and stamped at create time, so an existing mass regenerates
-         *  from the record and never from a heuristic that may change; it is
-         *  re-resolved (and an echoed value overridden) when an edit changes
-         *  `twistInDegrees`, so a retwisted mass matches a fresh build of the
-         *  same angle. Absent exactly when the mass is neither twisted nor
-         *  tapered. */
-        levels?: number
-      }
-      operations?: OperationRecord[]
-    }
-  | {
-      kind: "revolution"
-      version: 1
-      values: {
-        contour: ContourRecord
-        axisOrigin: XYZ
-        axisDirection: XYZ
-        angleInDegrees: number
-      }
-      operations?: OperationRecord[]
-    }
-  | {
-      kind: "loft"
-      version: 1
-      values: { sections: ContourRecord[]; options?: LoftOptions }
-      operations?: OperationRecord[]
-    }
-  | {
-      kind: "sweep"
-      version: 1
-      values: { profile: ContourRecord; path: XYZ[]; options?: SweepOptions }
-      operations?: OperationRecord[]
-    }
-  | {
-      kind: "sweepAlongCurve"
-      version: 1
-      values: {
-        profile: ContourRecord
-        path: CurveRecord[]
-        options?: SweepAlongCurveRecordOptions
-      }
-      operations?: OperationRecord[]
-    }
-
-/**
- * The argument of `design.update.parameters`: either a **partial** of a
- * record's `values` (plus an optional `operations` list) — keys you leave out
- * stay as they are — or the **whole record** you read from
- * `design.query.getParameters`, edited. `kind` and `version` are immutable.
- */
-export type MassParametersPatch = MassParametersRecord | Record<string, ParameterPatchValue>
-
-// ── Schemas ─────────────────────────────────────────────────────────────────
-// Array bounds are CONTRACT, not silent truncation: a record beyond them fails
-// validation. They keep a record inside the serialization budget of the save
-// and collaboration payloads it rides in. They bind RECORDS only — the shipped
-// creator schemas (loft sections, sweep path, fillet/chamfer edges, shell faces)
-// stay uncapped; an over-cap call still builds and the host simply mints no
-// record for it (the mass is then ordinary, non-parametric geometry).
-
-/** Maximum through-points in one authored spline curve record. */
-export const MAX_SPLINE_THROUGH_POINTS = 256
-/** Maximum control points in one exact-NURBS spline curve record. */
-export const MAX_SPLINE_POLES = 512
-/** Maximum path points in a sweep record. */
-export const MAX_SWEEP_PATH_POINTS = 512
-/** Maximum path curves in a sweep-along-a-curve record. */
-export const MAX_PATH_CURVES = 64
-/** Maximum cross-sections in a loft record. */
-export const MAX_LOFT_SECTIONS = 32
-/** Maximum sections a twisted or tapered extrusion record is built from. */
-export const MAX_TWIST_LEVELS = 64
-/** Maximum boundary curves in one profile loop record. */
-export const MAX_PROFILE_CURVES = 256
-/** Maximum hole loops in one contour record. */
-export const MAX_CONTOUR_HOLES = 64
-
-/** A point in space — `{ x, y, z }`, all finite. */
-export const XYZ: z.ZodType<XYZ, XYZ> = z.strictObject({
-  x: z.number().finite(),
-  y: z.number().finite(),
-  z: z.number().finite(),
-})
-
-/** One boundary curve of a profile record. See {@linkcode CurveRecord}. */
-export const CurveRecord: z.ZodType<CurveRecord, CurveRecord> = z.discriminatedUnion("type", [
-  z.strictObject({ type: z.literal("line"), start: XYZ, end: XYZ }),
-  z.strictObject({ type: z.literal("arc"), start: XYZ, end: XYZ, centre: XYZ, axis: XYZ }),
-  z.strictObject({
-    type: z.literal("circle"),
-    centre: XYZ,
-    axis: XYZ,
-    radius: z.number().finite().positive(),
-  }),
-  z.strictObject({
-    type: z.literal("splineThrough"),
-    fitVersion: z.literal(1),
-    throughPoints: z.array(XYZ).min(2).max(MAX_SPLINE_THROUGH_POINTS),
-  }),
-  z.strictObject({
-    type: z.literal("splinePoles"),
-    degree: z.number().int().positive(),
-    knots: z.array(z.number().finite()).min(2),
-    mults: z.array(z.number().int().positive()).min(2),
-    poles: z.array(XYZ).min(2).max(MAX_SPLINE_POLES),
-  }),
-])
-
-/** A closed boundary loop. See {@linkcode ProfileRecord}. */
-export const ProfileRecord: z.ZodType<ProfileRecord, ProfileRecord> = z.strictObject({
-  curves: z.array(CurveRecord).min(1).max(MAX_PROFILE_CURVES),
-})
-
-/** An outer loop plus its holes. See {@linkcode ContourRecord}. */
-export const ContourRecord: z.ZodType<ContourRecord, ContourRecord> = z.strictObject({
-  outer: ProfileRecord,
-  holes: z.array(ProfileRecord).max(MAX_CONTOUR_HOLES),
-})
-
-/** Optional loft behaviour switches. See {@linkcode LoftOptions}. */
-export const LoftOptions: z.ZodType<LoftOptions, LoftOptions> = z.strictObject({
-  compatibility: z.enum(["strict", "auto"]).optional(),
-  seamAlignment: z.enum(["authored", "auto"]).optional(),
-  smoothing: z.enum(["ruled", "smooth"]).optional(),
-})
-
-/** See {@linkcode SweepAlongCurveRecordOptions}. */
-export const SweepAlongCurveRecordOptions: z.ZodType<
-  SweepAlongCurveRecordOptions,
-  SweepAlongCurveRecordOptions
-> = z.strictObject({
-  orientation: z.enum(["frenet", "fixed", "upright"]).optional(),
-})
-
-/** Optional sweep scale law and corner transition. See {@linkcode SweepOptions}. */
-export const SweepOptions: z.ZodType<SweepOptions, SweepOptions> = z.strictObject({
-  startScale: z.number().finite().optional(),
-  endScale: z.number().finite().optional(),
-  scales: z.array(z.number().finite()).optional(),
-  transition: z
-    .union([
-      z.literal("miter"),
-      z.literal("round"),
-      z.strictObject({ bevel: z.number().finite() }),
-    ])
-    .optional(),
-})
-
-// `operations` rides beside `values` on every kind — additive and optional, so
-// `version` stays 1. An older reader that predates `operations` fails
-// `safeParse` on a record carrying it and degrades the mass to non-parametric;
-// it never blocks a load.
-// No `.min(1)`: `design.update.parameters` documents `{ operations: [] }` as the
-// drop-every-operation idiom, and the whole record you read back — edited to an
-// empty list — must patch the same way. The host normalises `[]` to an absent
-// key before storing, so a stored record never carries one.
-const RecordOperations = z.array(OperationRecord).max(MAX_OPERATIONS).optional()
-
-/**
- * A mass's creation recipe. See {@linkcode MassParametersRecord}.
- *
- * `version` is a literal `1`: a restore that reads an unknown version fails
- * `safeParse` and the mass degrades to non-parametric — editability is lost,
- * geometry never is, and load is never blocked. Future versions add a migration
- * at the restore site.
- */
-export const MassParametersRecord: z.ZodType<MassParametersRecord, MassParametersRecord> = z.discriminatedUnion("kind", [
-  z.strictObject({
-    kind: z.literal("sphere"),
-    version: z.literal(1),
-    values: z.strictObject({ centre: XYZ, radius: z.number().finite().positive() }),
-    operations: RecordOperations,
-  }),
-  z.strictObject({
-    kind: z.literal("cylinder"),
-    version: z.literal(1),
-    values: z.strictObject({
-      base: XYZ,
-      axis: XYZ,
-      radius: z.number().finite().positive(),
-      height: z.number().finite().positive(),
-    }),
-    operations: RecordOperations,
-  }),
-  z.strictObject({
-    kind: z.literal("cone"),
-    version: z.literal(1),
-    values: z.strictObject({
-      base: XYZ,
-      axis: XYZ,
-      baseRadius: z.number().finite().positive(),
-      topRadius: z.number().finite().nonnegative(),
-      height: z.number().finite().positive(),
-    }),
-    operations: RecordOperations,
-  }),
-  z.strictObject({
-    kind: z.literal("torus"),
-    version: z.literal(1),
-    values: z.strictObject({
-      centre: XYZ,
-      axis: XYZ,
-      majorRadius: z.number().finite().positive(),
-      minorRadius: z.number().finite().positive(),
-    }),
-    operations: RecordOperations,
-  }),
-  z.strictObject({
-    kind: z.literal("extrusion"),
-    version: z.literal(1),
-    values: z.strictObject({
-      contour: ContourRecord,
-      direction: XYZ,
-      amount: z.number().finite(),
-      twistInDegrees: z.number().finite().optional(),
-      topScale: z.number().finite().positive().optional(),
-      levels: z.number().int().min(2).max(MAX_TWIST_LEVELS).optional(),
-    }),
-    operations: RecordOperations,
-  }),
-  z.strictObject({
-    kind: z.literal("revolution"),
-    version: z.literal(1),
-    values: z.strictObject({
-      contour: ContourRecord,
-      axisOrigin: XYZ,
-      axisDirection: XYZ,
-      angleInDegrees: z.number().finite().positive().max(360),
-    }),
-    operations: RecordOperations,
-  }),
-  z.strictObject({
-    kind: z.literal("loft"),
-    version: z.literal(1),
-    values: z.strictObject({
-      sections: z.array(ContourRecord).min(2).max(MAX_LOFT_SECTIONS),
-      options: LoftOptions.optional(),
-    }),
-    operations: RecordOperations,
-  }),
-  z.strictObject({
-    kind: z.literal("sweep"),
-    version: z.literal(1),
-    values: z.strictObject({
-      profile: ContourRecord,
-      path: z.array(XYZ).min(2).max(MAX_SWEEP_PATH_POINTS),
-      options: SweepOptions.optional(),
-    }),
-    operations: RecordOperations,
-  }),
-  z.strictObject({
-    kind: z.literal("sweepAlongCurve"),
-    version: z.literal(1),
-    values: z.strictObject({
-      profile: ContourRecord,
-      path: z.array(CurveRecord).min(1).max(MAX_PATH_CURVES),
-      options: SweepAlongCurveRecordOptions.optional(),
-    }),
-    operations: RecordOperations,
-  }),
-])
-
-/**
- * The argument of `design.update.parameters`. See {@linkcode MassParametersPatch}.
- * The full-record form is recognised by carrying both `kind` and `values`;
- * which keys a kind actually has is checked host-side, where the error can name
- * them.
- */
-export const MassParametersPatch: z.ZodType<MassParametersPatch, MassParametersPatch> = z.union([
-  MassParametersRecord,
-  z.record(z.string(), ParameterPatchValue),
-])
+import * as z from "zod"
+import { MAX_OPERATIONS, OperationRecord, ParameterPatchValue } from "./massParameters.ops"
+
+// The selectors, the operation record and the patch-value union live in
+// `massParameters.ops.ts` (split so each module stays small enough for the
+// agent to read in one go) and are re-exported here, so every import path
+// keeps working.
+export * from "./massParameters.ops"
+
+/**
+ * Mass **creation-parameter records** — the recipe a parametric mass was built
+ * from, shared verbatim by plugin-core, the Snaptrude host, and the agent
+ * runtime. There is one schema, not three hand-kept copies.
+ *
+ * A record is present on a mass committed from a `core.geom.create` brep
+ * constructor that carries a recipe (the four primitives, extrusion,
+ * revolution, loft, sweep). A fillet, chamfer, shell or offset of a **recorded**
+ * solid keeps the record: `kind` stays the base constructor and the step is
+ * appended to the record's `operations` list (see {@linkcode OperationRecord}).
+ * The record is absent — `null` — for everything
+ * else: drawn masses, imported geometry, booleans, split parts,
+ * `brepFromFaces`/`brepFromMesh`, and any operation on a solid that carried no
+ * record. Geometry there is not a pure function of a legible parameter set, and
+ * a record must never be a lie.
+ *
+ * Read one with `design.query.getParameters`.
+ *
+ * Everything here is **pure JSON** by construction — plain objects, numbers and
+ * arrays only, one `{x, y, z}` point shape everywhere (no tuples, no class
+ * instances): records are persisted by enumerable-field reflection, cloned with
+ * `structuredClone`, and round-tripped through the collaboration wire.
+ */
+
+/** A point in space. The single point shape used across every record. */
+export type XYZ = { x: number; y: number; z: number }
+
+/**
+ * One boundary curve of a profile record.
+ *
+ * The two spline forms are either/or, never both: a curve authored through
+ * points carries `splineThrough` (patch the points and the fit re-runs), and a
+ * curve with no through-point provenance — read back off an edge, or authored
+ * from control vertices — carries `splinePoles` and is re-minted verbatim.
+ * There is no variant holding both, so a `throughPoints` edit can never leave
+ * stale poles behind.
+ */
+export type CurveRecord =
+  | { type: "line"; start: XYZ; end: XYZ }
+  | { type: "arc"; start: XYZ; end: XYZ; centre: XYZ; axis: XYZ }
+  | { type: "circle"; centre: XYZ; axis: XYZ; radius: number }
+  /** Authored via splineFromPoints / profileFromSplinePoints. The through-points
+   *  ARE the recipe; regeneration re-runs the fit version named by
+   *  `fitVersion`. Several chained runs in one contour re-fit as ONE loop; use
+   *  splinePoles to keep their tangents. */
+  | { type: "splineThrough"; fitVersion: 1; throughPoints: XYZ[] }
+  /** No through-points known (authored from control points, or read back off
+   *  an edge). Rebuilt verbatim from these exact poles, knots and
+   *  multiplicities. */
+  | { type: "splinePoles"; degree: number; knots: number[]; mults: number[]; poles: XYZ[] }
+
+/** A closed boundary loop, as an ordered list of curves. */
+export type ProfileRecord = { curves: CurveRecord[] }
+
+/** An outer loop plus its holes — the cross-section shape of a recipe. */
+export type ContourRecord = { outer: ProfileRecord; holes: ProfileRecord[] }
+
+/** Optional loft behaviour switches, mirroring `core.geom.create.brepFromLoft`. */
+export type LoftOptions = {
+  compatibility?: "strict" | "auto"
+  seamAlignment?: "authored" | "auto"
+  /** `"ruled"` (default) keeps the sides straight: every pair of sections
+   *  joined by flat sides. `"smooth"` lofts every section in ONE pass, so the
+   *  sides curve continuously through the intermediates. */
+  smoothing?: "ruled" | "smooth"
+}
+
+/**
+ * How a swept profile turns along its path, mirroring
+ * `core.geom.create.brepFromSweepAlongCurve`. `"upright"` keeps the profile's up
+ * aligned with world up, `"frenet"` lets it roll with the path's curvature, and
+ * `"fixed"` carries the authored frame along unchanged.
+ */
+export type SweepOrientation = "frenet" | "fixed" | "upright"
+
+/** Optional sweep-along-a-curve switches. Pure JSON: the creator's own bag also
+ *  takes a `rail` curve, which is a live handle and never reaches a record. */
+export type SweepAlongCurveRecordOptions = { orientation?: SweepOrientation }
+
+/** Optional sweep scale law and corner transition, mirroring `core.geom.create.brepFromSweep`. */
+export type SweepOptions = {
+  startScale?: number
+  endScale?: number
+  scales?: number[]
+  transition?: "miter" | "round" | { bevel: number }
+}
+
+/** A face's surface kind — the vocabulary of `core.geom.query.face.getSurfaceKind`. */
+export type SurfaceKind = "plane" | "cylinder" | "cone" | "sphere" | "torus" | "spline"
+
+/** An edge's curve kind. Both spline forms of {@linkcode CurveRecord} report `"spline"`. */
+export type CurveKind = "line" | "arc" | "circle" | "spline"
+
+/**
+ * A mass's creation recipe: the constructor `kind`, a schema `version`, the
+ * `values` that constructor was called with, and the kernel `operations`
+ * (fillet / chamfer / shell / offset) applied on top, in order. Points and axes
+ * are in the mass's own local frame when stored; `design.query.getParameters`
+ * returns them in world coordinates. `operations` is frame-free. One variant
+ * per constructor `kind`; its `values` are that constructor's own arguments.
+ *
+ * `kind` stays the base constructor even after operations: a shelled, filleted
+ * sphere is still `{ kind: "sphere", operations: [shell, fillet] }`.
+ */
+export type MassParametersRecord =
+  | {
+      kind: "sphere"
+      version: 1
+      values: { centre: XYZ; radius: number }
+      operations?: OperationRecord[]
+    }
+  | {
+      kind: "cylinder"
+      version: 1
+      values: { base: XYZ; axis: XYZ; radius: number; height: number }
+      operations?: OperationRecord[]
+    }
+  | {
+      kind: "cone"
+      version: 1
+      values: { base: XYZ; axis: XYZ; baseRadius: number; topRadius: number; height: number }
+      operations?: OperationRecord[]
+    }
+  | {
+      kind: "torus"
+      version: 1
+      values: { centre: XYZ; axis: XYZ; majorRadius: number; minorRadius: number }
+      operations?: OperationRecord[]
+    }
+  | {
+      kind: "extrusion"
+      version: 1
+      values: {
+        contour: ContourRecord
+        direction: XYZ
+        amount: number
+        /** Total rotation base → top about `direction`, through the base
+         *  contour's centroid, in DEGREES — an angle, never converted. Absent
+         *  or 0 is a straight extrusion. Positive turns the top CLOCKWISE seen
+         *  from the far end of `direction` looking back at the base — for the
+         *  usual upward extrusion, that is the plan view from above. */
+        twistInDegrees?: number
+        /** Top outline scale about the same axis, a ratio — never converted.
+         *  Absent or 1 is a straight extrusion. */
+        topScale?: number
+        /** How many sections the twist/taper was built from, a count (2..64).
+         *  Resolved and stamped at create time, so an existing mass regenerates
+         *  from the record and never from a heuristic that may change; it is
+         *  re-resolved (and an echoed value overridden) when an edit changes
+         *  `twistInDegrees`, so a retwisted mass matches a fresh build of the
+         *  same angle. Absent exactly when the mass is neither twisted nor
+         *  tapered. */
+        levels?: number
+      }
+      operations?: OperationRecord[]
+    }
+  | {
+      kind: "revolution"
+      version: 1
+      values: {
+        contour: ContourRecord
+        axisOrigin: XYZ
+        axisDirection: XYZ
+        angleInDegrees: number
+      }
+      operations?: OperationRecord[]
+    }
+  | {
+      kind: "loft"
+      version: 1
+      values: { sections: ContourRecord[]; options?: LoftOptions }
+      operations?: OperationRecord[]
+    }
+  | {
+      kind: "sweep"
+      version: 1
+      values: { profile: ContourRecord; path: XYZ[]; options?: SweepOptions }
+      operations?: OperationRecord[]
+    }
+  | {
+      kind: "sweepAlongCurve"
+      version: 1
+      values: {
+        profile: ContourRecord
+        path: CurveRecord[]
+        options?: SweepAlongCurveRecordOptions
+      }
+      operations?: OperationRecord[]
+    }
+
+/**
+ * The argument of `design.update.parameters`: either a **partial** of a
+ * record's `values` (plus an optional `operations` list) — keys you leave out
+ * stay as they are — or the **whole record** you read from
+ * `design.query.getParameters`, edited. `kind` and `version` are immutable.
+ */
+export type MassParametersPatch = MassParametersRecord | Record<string, ParameterPatchValue>
+
+// ── Schemas ─────────────────────────────────────────────────────────────────
+// Array bounds are CONTRACT, not silent truncation: a record beyond them fails
+// validation. They keep a record inside the serialization budget of the save
+// and collaboration payloads it rides in. They bind RECORDS only — the shipped
+// creator schemas (loft sections, sweep path, fillet/chamfer edges, shell faces)
+// stay uncapped; an over-cap call still builds and the host simply mints no
+// record for it (the mass is then ordinary, non-parametric geometry).
+
+/** Maximum through-points in one authored spline curve record. */
+export const MAX_SPLINE_THROUGH_POINTS = 256
+/** Maximum control points in one exact-NURBS spline curve record. */
+export const MAX_SPLINE_POLES = 512
+/** Maximum path points in a sweep record. */
+export const MAX_SWEEP_PATH_POINTS = 512
+/** Maximum path curves in a sweep-along-a-curve record. */
+export const MAX_PATH_CURVES = 64
+/** Maximum cross-sections in a loft record. */
+export const MAX_LOFT_SECTIONS = 32
+/** Maximum sections a twisted or tapered extrusion record is built from. */
+export const MAX_TWIST_LEVELS = 64
+/** Maximum boundary curves in one profile loop record. */
+export const MAX_PROFILE_CURVES = 256
+/** Maximum hole loops in one contour record. */
+export const MAX_CONTOUR_HOLES = 64
+
+/** A point in space — `{ x, y, z }`, all finite. */
+export const XYZ: z.ZodType<XYZ, XYZ> = z.strictObject({
+  x: z.number().finite(),
+  y: z.number().finite(),
+  z: z.number().finite(),
+})
+
+/** One boundary curve of a profile record. See {@linkcode CurveRecord}. */
+export const CurveRecord: z.ZodType<CurveRecord, CurveRecord> = z.discriminatedUnion("type", [
+  z.strictObject({ type: z.literal("line"), start: XYZ, end: XYZ }),
+  z.strictObject({ type: z.literal("arc"), start: XYZ, end: XYZ, centre: XYZ, axis: XYZ }),
+  z.strictObject({
+    type: z.literal("circle"),
+    centre: XYZ,
+    axis: XYZ,
+    radius: z.number().finite().positive(),
+  }),
+  z.strictObject({
+    type: z.literal("splineThrough"),
+    fitVersion: z.literal(1),
+    throughPoints: z.array(XYZ).min(2).max(MAX_SPLINE_THROUGH_POINTS),
+  }),
+  z.strictObject({
+    type: z.literal("splinePoles"),
+    degree: z.number().int().positive(),
+    knots: z.array(z.number().finite()).min(2),
+    mults: z.array(z.number().int().positive()).min(2),
+    poles: z.array(XYZ).min(2).max(MAX_SPLINE_POLES),
+  }),
+])
+
+/** A closed boundary loop. See {@linkcode ProfileRecord}. */
+export const ProfileRecord: z.ZodType<ProfileRecord, ProfileRecord> = z.strictObject({
+  curves: z.array(CurveRecord).min(1).max(MAX_PROFILE_CURVES),
+})
+
+/** An outer loop plus its holes. See {@linkcode ContourRecord}. */
+export const ContourRecord: z.ZodType<ContourRecord, ContourRecord> = z.strictObject({
+  outer: ProfileRecord,
+  holes: z.array(ProfileRecord).max(MAX_CONTOUR_HOLES),
+})
+
+/** Optional loft behaviour switches. See {@linkcode LoftOptions}. */
+export const LoftOptions: z.ZodType<LoftOptions, LoftOptions> = z.strictObject({
+  compatibility: z.enum(["strict", "auto"]).optional(),
+  seamAlignment: z.enum(["authored", "auto"]).optional(),
+  smoothing: z.enum(["ruled", "smooth"]).optional(),
+})
+
+/** See {@linkcode SweepAlongCurveRecordOptions}. */
+export const SweepAlongCurveRecordOptions: z.ZodType<
+  SweepAlongCurveRecordOptions,
+  SweepAlongCurveRecordOptions
+> = z.strictObject({
+  orientation: z.enum(["frenet", "fixed", "upright"]).optional(),
+})
+
+/** Optional sweep scale law and corner transition. See {@linkcode SweepOptions}. */
+export const SweepOptions: z.ZodType<SweepOptions, SweepOptions> = z.strictObject({
+  startScale: z.number().finite().optional(),
+  endScale: z.number().finite().optional(),
+  scales: z.array(z.number().finite()).optional(),
+  transition: z
+    .union([
+      z.literal("miter"),
+      z.literal("round"),
+      z.strictObject({ bevel: z.number().finite() }),
+    ])
+    .optional(),
+})
+
+// `operations` rides beside `values` on every kind — additive and optional, so
+// `version` stays 1. An older reader that predates `operations` fails
+// `safeParse` on a record carrying it and degrades the mass to non-parametric;
+// it never blocks a load.
+// No `.min(1)`: `design.update.parameters` documents `{ operations: [] }` as the
+// drop-every-operation idiom, and the whole record you read back — edited to an
+// empty list — must patch the same way. The host normalises `[]` to an absent
+// key before storing, so a stored record never carries one.
+const RecordOperations = z.array(OperationRecord).max(MAX_OPERATIONS).optional()
+
+/**
+ * A mass's creation recipe. See {@linkcode MassParametersRecord}.
+ *
+ * `version` is a literal `1`: a restore that reads an unknown version fails
+ * `safeParse` and the mass degrades to non-parametric — editability is lost,
+ * geometry never is, and load is never blocked. Future versions add a migration
+ * at the restore site.
+ */
+export const MassParametersRecord: z.ZodType<MassParametersRecord, MassParametersRecord> = z.discriminatedUnion("kind", [
+  z.strictObject({
+    kind: z.literal("sphere"),
+    version: z.literal(1),
+    values: z.strictObject({ centre: XYZ, radius: z.number().finite().positive() }),
+    operations: RecordOperations,
+  }),
+  z.strictObject({
+    kind: z.literal("cylinder"),
+    version: z.literal(1),
+    values: z.strictObject({
+      base: XYZ,
+      axis: XYZ,
+      radius: z.number().finite().positive(),
+      height: z.number().finite().positive(),
+    }),
+    operations: RecordOperations,
+  }),
+  z.strictObject({
+    kind: z.literal("cone"),
+    version: z.literal(1),
+    values: z.strictObject({
+      base: XYZ,
+      axis: XYZ,
+      baseRadius: z.number().finite().positive(),
+      topRadius: z.number().finite().nonnegative(),
+      height: z.number().finite().positive(),
+    }),
+    operations: RecordOperations,
+  }),
+  z.strictObject({
+    kind: z.literal("torus"),
+    version: z.literal(1),
+    values: z.strictObject({
+      centre: XYZ,
+      axis: XYZ,
+      majorRadius: z.number().finite().positive(),
+      minorRadius: z.number().finite().positive(),
+    }),
+    operations: RecordOperations,
+  }),
+  z.strictObject({
+    kind: z.literal("extrusion"),
+    version: z.literal(1),
+    values: z.strictObject({
+      contour: ContourRecord,
+      direction: XYZ,
+      amount: z.number().finite(),
+      twistInDegrees: z.number().finite().optional(),
+      topScale: z.number().finite().positive().optional(),
+      levels: z.number().int().min(2).max(MAX_TWIST_LEVELS).optional(),
+    }),
+    operations: RecordOperations,
+  }),
+  z.strictObject({
+    kind: z.literal("revolution"),
+    version: z.literal(1),
+    values: z.strictObject({
+      contour: ContourRecord,
+      axisOrigin: XYZ,
+      axisDirection: XYZ,
+      angleInDegrees: z.number().finite().positive().max(360),
+    }),
+    operations: RecordOperations,
+  }),
+  z.strictObject({
+    kind: z.literal("loft"),
+    version: z.literal(1),
+    values: z.strictObject({
+      sections: z.array(ContourRecord).min(2).max(MAX_LOFT_SECTIONS),
+      options: LoftOptions.optional(),
+    }),
+    operations: RecordOperations,
+  }),
+  z.strictObject({
+    kind: z.literal("sweep"),
+    version: z.literal(1),
+    values: z.strictObject({
+      profile: ContourRecord,
+      path: z.array(XYZ).min(2).max(MAX_SWEEP_PATH_POINTS),
+      options: SweepOptions.optional(),
+    }),
+    operations: RecordOperations,
+  }),
+  z.strictObject({
+    kind: z.literal("sweepAlongCurve"),
+    version: z.literal(1),
+    values: z.strictObject({
+      profile: ContourRecord,
+      path: z.array(CurveRecord).min(1).max(MAX_PATH_CURVES),
+      options: SweepAlongCurveRecordOptions.optional(),
+    }),
+    operations: RecordOperations,
+  }),
+])
+
+/**
+ * The argument of `design.update.parameters`. See {@linkcode MassParametersPatch}.
+ * The full-record form is recognised by carrying both `kind` and `values`;
+ * which keys a kind actually has is checked host-side, where the error can name
+ * them.
+ */
+export const MassParametersPatch: z.ZodType<MassParametersPatch, MassParametersPatch> = z.union([
+  MassParametersRecord,
+  z.record(z.string(), ParameterPatchValue),
+])