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

package/src/api/entity/buildableEnvelope.ts

@@ -1,322 +1,397 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-
-/**
- * Buildable Envelope management — create and update parametric zoning envelopes.
- *
- * A **buildable envelope** is the regulated volume inside which a building may
- * be massed. The host owns envelope identity: {@linkcode PluginBuildableEnvelopeApi.create create}
- * mints a `buildableEnvelopeId` and returns it; {@linkcode PluginBuildableEnvelopeApi.update update}
- * requires that id to target the existing envelope.
- *
- * Accessed via `snaptrude.entity.buildableEnvelope`.
- */
-export abstract class PluginBuildableEnvelopeApi {
-  constructor() {}
-
-  /**
-   * Create a new parametric buildable envelope — the zoning-regulated volume a
-   * building may occupy — generated from a site polygon, tiered setbacks, a
-   * height or floor-count cap, and optional FAR and lot-coverage limits.
-   *
-   * @param sitePolygon - Site polygon vertices in `lengthUnit`; minimum 3 vertices.
-   * @param lengthUnit - Unit used by all length fields (`"ft" | "m"`).
-   * @param setbacks - Setback profile, ground tier first; minimum 1 tier.
-   * @param verticalCap - Maximum height or floor count.
-   * @param floorToFloor - Required floor-to-floor height in `lengthUnit`.
-   * @param farRatio - Optional FAR value, positive when provided.
-   * @param lotCoverageMaxPct - Optional lot coverage cap, `0..100`.
-   * @returns A {@linkcode PluginBuildableEnvelopeCreateResult} with the
-   *   `buildableEnvelopeId` of the created envelope.
-   * @throws If validation fails or generation produces no renderable geometry.
-   *
-   * @examplePrompt Create a buildable envelope for my site
-   * @examplePrompt Generate the zoning envelope with 10ft front setbacks
-   * @examplePrompt Show the maximum buildable volume with a 150ft height limit
-   * @examplePrompt Model the allowable massing from the setback rules
-   * @examplePrompt Create a zoning envelope capped at 12 floors with FAR 3
-   *
-   * # Example
-   * ```ts
-   * const { buildableEnvelopeId } = await snaptrude.entity.buildableEnvelope.create(
-   *   [
-   *     { x: 0, z: 0 },
-   *     { x: 100, z: 0 },
-   *     { x: 100, z: 80 },
-   *     { x: 0, z: 80 },
-   *   ],
-   *   "ft",
-   *   [
-   *     { aboveHeight: 0, front: 10, side: 5, rear: 10 },
-   *     { aboveHeight: 100, front: 20, side: 10, rear: 20 },
-   *   ],
-   *   { kind: "max_height", maxHeight: 150 },
-   *   12,
-   * )
-   * ```
-   *
-   * @deprecated Use `design.create.buildableEnvelope`
-   */
-  public abstract create(
-    sitePolygon: PluginBuildableEnvelopePolygonVertex[],
-    lengthUnit: "ft" | "m",
-    setbacks: PluginBuildableEnvelopeSetbackTier[],
-    verticalCap: PluginBuildableEnvelopeVerticalCap,
-    floorToFloor: number,
-    farRatio?: number,
-    lotCoverageMaxPct?: number
-  ): PluginApiReturn<PluginBuildableEnvelopeCreateResult>
-
-  /**
-   * Update an existing parametric buildable envelope — regenerate the zoning
-   * volume from a revised site polygon, setbacks, vertical cap, or FAR and
-   * lot-coverage limits, keeping the same envelope id.
-   *
-   * @param buildableEnvelopeId - Existing envelope ID to update; non-empty and
-   *   must match an existing envelope on the canvas.
-   * @param sitePolygon - Site polygon vertices in `lengthUnit`; minimum 3 vertices.
-   * @param lengthUnit - Unit used by all length fields (`"ft" | "m"`).
-   * @param setbacks - Setback profile, ground tier first; minimum 1 tier.
-   * @param verticalCap - Maximum height or floor count.
-   * @param floorToFloor - Required floor-to-floor height in `lengthUnit`.
-   * @param farRatio - Optional FAR value, positive when provided.
-   * @param lotCoverageMaxPct - Optional lot coverage cap, `0..100`.
-   * @returns A {@linkcode PluginBuildableEnvelopeUpdateResult} with the
-   *   `buildableEnvelopeId` of the updated envelope.
-   * @throws If validation fails, the envelope does not exist, or generation
-   *   produces no renderable geometry.
-   *
-   * @examplePrompt Change the envelope's height limit to 175 feet
-   * @examplePrompt Update the setbacks on the buildable envelope
-   * @examplePrompt Regenerate the zoning envelope with a new site boundary
-   * @examplePrompt Increase the FAR on the buildable volume
-   * @examplePrompt Modify the envelope to allow 15 storeys instead
-   *
-   * # Example
-   * ```ts
-   * const { buildableEnvelopeId } = await snaptrude.entity.buildableEnvelope.update(
-   *   existingId,
-   *   [
-   *     { x: 0, z: 0 },
-   *     { x: 100, z: 0 },
-   *     { x: 100, z: 80 },
-   *     { x: 0, z: 80 },
-   *   ],
-   *   "ft",
-   *   [{ aboveHeight: 0, front: 10, side: 5, rear: 10 }],
-   *   { kind: "max_height", maxHeight: 175 },
-   *   12,
-   * )
-   * ```
-   *
-   * @deprecated Use `design.update.buildableEnvelope`
-   */
-  public abstract update(
-    buildableEnvelopeId: string,
-    sitePolygon: PluginBuildableEnvelopePolygonVertex[],
-    lengthUnit: "ft" | "m",
-    setbacks: PluginBuildableEnvelopeSetbackTier[],
-    verticalCap: PluginBuildableEnvelopeVerticalCap,
-    floorToFloor: number,
-    farRatio?: number,
-    lotCoverageMaxPct?: number
-  ): PluginApiReturn<PluginBuildableEnvelopeUpdateResult>
-}
-
-/**
- * Site polygon vertex in the request `lengthUnit`.
- *
- * Vertices may be passed as `{x, z}` objects or `[x, z]` tuples. Numeric
- * values must be finite (no `NaN` or `±Infinity`).
- */
-export const PluginBuildableEnvelopePolygonVertex = z.union([
-  z.object({ x: z.number().finite(), z: z.number().finite() }).strict(),
-  z.tuple([z.number().finite(), z.number().finite()]),
-])
-
-export type PluginBuildableEnvelopePolygonVertex = z.infer<
-  typeof PluginBuildableEnvelopePolygonVertex
->
-
-/**
- * Vertical cap for a buildable envelope.
- *
- * Use exactly one shape:
- * - `{ kind: "max_height", maxHeight }`
- * - `{ kind: "max_floors", maxFloors }`
- *
- * Floor-to-floor height is not nested here; it is always supplied as the
- * top-level `floorToFloor` argument.
- */
-export const PluginBuildableEnvelopeVerticalCap = z.discriminatedUnion("kind", [
-  z.object({
-    kind: z.literal("max_height"),
-    maxHeight: z.number().finite().positive(),
-  }).strict(),
-  z.object({
-    kind: z.literal("max_floors"),
-    maxFloors: z.number().finite().int().positive(),
-  }).strict(),
-])
-
-export type PluginBuildableEnvelopeVerticalCap = z.infer<
-  typeof PluginBuildableEnvelopeVerticalCap
->
-
-/**
- * One tier of a buildable envelope's setback profile.
- *
- * Tiers are ordered by `aboveHeight`. The first tier (index 0) must have
- * `aboveHeight: 0` and describes the ground footprint; each subsequent tier
- * describes the complete setback at a strictly greater height. Each tier
- * carries its own `front`, `side`, and `rear` values — there is no
- * inheritance from earlier tiers.
- *
- * All numeric values must be finite and nonnegative, in the request
- * `lengthUnit`.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `aboveHeight` | `number` | Height at or above which this tier applies; the ground tier uses `0` |
- * | `front` | `number` | Front setback for this tier |
- * | `side` | `number` | Side setback for this tier |
- * | `rear` | `number` | Rear setback for this tier |
- */
-export const PluginBuildableEnvelopeSetbackTier = z.object({
-  aboveHeight: z.number().finite().nonnegative(),
-  front: z.number().finite().nonnegative(),
-  side: z.number().finite().nonnegative(),
-  rear: z.number().finite().nonnegative(),
-}).strict()
-
-export type PluginBuildableEnvelopeSetbackTier = z.infer<
-  typeof PluginBuildableEnvelopeSetbackTier
->
-
-// Enforces setback tier ordering invariants on the parsed args shape:
-//   - setbacks[0].aboveHeight === 0
-//   - aboveHeight strictly increasing thereafter
-// Length >= 1 is enforced earlier by z.array(...).min(1).
-function refineSetbackTiers(
-  args: { setbacks: PluginBuildableEnvelopeSetbackTier[] },
-  ctx: z.RefinementCtx
-): void {
-  const tiers = args.setbacks
-  if (tiers.length === 0) return
-  if (tiers[0].aboveHeight !== 0) {
-    ctx.addIssue({
-      code: z.ZodIssueCode.custom,
-      path: ["setbacks", 0, "aboveHeight"],
-      message: "Ground tier required: setbacks[0].aboveHeight must be 0.",
-    })
-  }
-  for (let i = 1; i < tiers.length; i++) {
-    if (!(tiers[i].aboveHeight > tiers[i - 1].aboveHeight)) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        path: ["setbacks", i, "aboveHeight"],
-        message:
-          "Setback tiers must be ordered by strictly increasing aboveHeight.",
-      })
-    }
-  }
-}
-
-/**
- * Arguments for {@linkcode PluginBuildableEnvelopeApi.create}.
- *
- * Strict schema. The host owns identity — no `buildableEnvelopeId` is accepted
- * on create; the id is minted by the host and returned in
- * {@linkcode PluginBuildableEnvelopeCreateResult}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `sitePolygon` | {@linkcode PluginBuildableEnvelopePolygonVertex}`[]` | Site polygon vertices in `lengthUnit`; minimum 3 vertices |
- * | `lengthUnit` | `"ft" \| "m"` | Unit used by all length fields |
- * | `setbacks` | {@linkcode PluginBuildableEnvelopeSetbackTier}`[]` | Setback profile, ground tier first; minimum 1 tier |
- * | `verticalCap` | {@linkcode PluginBuildableEnvelopeVerticalCap} | Maximum height or floor count |
- * | `floorToFloor` | `number` | Required floor-to-floor height in `lengthUnit` |
- * | `farRatio` | `number?` | Optional FAR value, positive when provided |
- * | `lotCoverageMaxPct` | `number?` | Optional lot coverage cap, `0..100` |
- */
-export const PluginBuildableEnvelopeCreateArgs = z
-  .object({
-    sitePolygon: z.array(PluginBuildableEnvelopePolygonVertex).min(3),
-    lengthUnit: z.union([z.literal("ft"), z.literal("m")]),
-    setbacks: z.array(PluginBuildableEnvelopeSetbackTier).min(1),
-    verticalCap: PluginBuildableEnvelopeVerticalCap,
-    floorToFloor: z.number().finite().positive(),
-    farRatio: z.number().finite().positive().optional(),
-    lotCoverageMaxPct: z.number().finite().min(0).max(100).optional(),
-  })
-  .strict()
-  .superRefine(refineSetbackTiers)
-
-export type PluginBuildableEnvelopeCreateArgs = z.infer<
-  typeof PluginBuildableEnvelopeCreateArgs
->
-
-/**
- * Result of {@linkcode PluginBuildableEnvelopeApi.create}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `buildableEnvelopeId` | `string` | Non-empty unique ID of the created buildable envelope |
- */
-export const PluginBuildableEnvelopeCreateResult = z.object({
-  buildableEnvelopeId: z.string().min(1),
-}).strict()
-
-export type PluginBuildableEnvelopeCreateResult = z.infer<
-  typeof PluginBuildableEnvelopeCreateResult
->
-
-/**
- * Arguments for {@linkcode PluginBuildableEnvelopeApi.update}.
- *
- * Strict schema. `buildableEnvelopeId` is required and identifies the prior
- * envelope on the canvas to update.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `buildableEnvelopeId` | `string` | Existing envelope ID to update; non-empty |
- * | `sitePolygon` | {@linkcode PluginBuildableEnvelopePolygonVertex}`[]` | Site polygon vertices in `lengthUnit`; minimum 3 vertices |
- * | `lengthUnit` | `"ft" \| "m"` | Unit used by all length fields |
- * | `setbacks` | {@linkcode PluginBuildableEnvelopeSetbackTier}`[]` | Setback profile, ground tier first; minimum 1 tier |
- * | `verticalCap` | {@linkcode PluginBuildableEnvelopeVerticalCap} | Maximum height or floor count |
- * | `floorToFloor` | `number` | Required floor-to-floor height in `lengthUnit` |
- * | `farRatio` | `number?` | Optional FAR value, positive when provided |
- * | `lotCoverageMaxPct` | `number?` | Optional lot coverage cap, `0..100` |
- */
-export const PluginBuildableEnvelopeUpdateArgs = z
-  .object({
-    buildableEnvelopeId: z.string().min(1),
-    sitePolygon: z.array(PluginBuildableEnvelopePolygonVertex).min(3),
-    lengthUnit: z.union([z.literal("ft"), z.literal("m")]),
-    setbacks: z.array(PluginBuildableEnvelopeSetbackTier).min(1),
-    verticalCap: PluginBuildableEnvelopeVerticalCap,
-    floorToFloor: z.number().finite().positive(),
-    farRatio: z.number().finite().positive().optional(),
-    lotCoverageMaxPct: z.number().finite().min(0).max(100).optional(),
-  })
-  .strict()
-  .superRefine(refineSetbackTiers)
-
-export type PluginBuildableEnvelopeUpdateArgs = z.infer<
-  typeof PluginBuildableEnvelopeUpdateArgs
->
-
-/**
- * Result of {@linkcode PluginBuildableEnvelopeApi.update}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `buildableEnvelopeId` | `string` | Non-empty unique ID of the updated buildable envelope |
- */
-export const PluginBuildableEnvelopeUpdateResult = z.object({
-  buildableEnvelopeId: z.string().min(1),
-}).strict()
-
-export type PluginBuildableEnvelopeUpdateResult = z.infer<
-  typeof PluginBuildableEnvelopeUpdateResult
->
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import {
+  PluginProgramSiteEdgeRole,
+  PluginProgramSiteEdgesEntry,
+} from "../program/site"
+
+/**
+ * Buildable Envelope management — create and update parametric zoning envelopes.
+ *
+ * A **buildable envelope** is the regulated volume inside which a building may
+ * be massed. The host owns envelope identity: {@linkcode PluginBuildableEnvelopeApi.create create}
+ * mints a `buildableEnvelopeId` and returns it; {@linkcode PluginBuildableEnvelopeApi.update update}
+ * requires that id to target the existing envelope.
+ *
+ * Accessed via `snaptrude.entity.buildableEnvelope`.
+ */
+export abstract class PluginBuildableEnvelopeApi {
+  constructor() {}
+
+  /**
+   * Create a new parametric buildable envelope — the zoning-regulated volume a
+   * building may occupy — generated from a site polygon, tiered setbacks, a
+   * height or floor-count cap, and optional FAR and lot-coverage limits.
+   *
+   * @param sitePolygon - Site polygon vertices in `lengthUnit`; minimum 3 vertices.
+   * @param lengthUnit - Unit used by all length fields (`"ft" | "m"`).
+   * @param setbacks - Setback profile, ground tier first; minimum 1 tier.
+   * @param verticalCap - Maximum height or floor count.
+   * @param floorToFloor - Required floor-to-floor height in `lengthUnit`.
+   * @param farRatio - Optional FAR value, positive when provided.
+   * @param lotCoverageMaxPct - Optional lot coverage cap, `0..100`.
+   * @returns A {@linkcode PluginBuildableEnvelopeCreateResult} with the
+   *   `buildableEnvelopeId` of the created envelope.
+   * @throws If validation fails or generation produces no renderable geometry.
+   *
+   * @examplePrompt Create a buildable envelope for my site
+   * @examplePrompt Generate the zoning envelope with 10ft front setbacks
+   * @examplePrompt Show the maximum buildable volume with a 150ft height limit
+   * @examplePrompt Model the allowable massing from the setback rules
+   * @examplePrompt Create a zoning envelope capped at 12 floors with FAR 3
+   *
+   * # Example
+   * ```ts
+   * const { buildableEnvelopeId } = await snaptrude.entity.buildableEnvelope.create(
+   *   [
+   *     { x: 0, z: 0 },
+   *     { x: 100, z: 0 },
+   *     { x: 100, z: 80 },
+   *     { x: 0, z: 80 },
+   *   ],
+   *   "ft",
+   *   [
+   *     { aboveHeight: 0, front: 10, side: 5, rear: 10 },
+   *     { aboveHeight: 100, front: 20, side: 10, rear: 20 },
+   *   ],
+   *   { kind: "max_height", maxHeight: 150 },
+   *   12,
+   * )
+   * ```
+   *
+   * @deprecated Use `design.create.buildableEnvelope`
+   */
+  public abstract create(
+    sitePolygon: PluginBuildableEnvelopePolygonVertex[],
+    lengthUnit: "ft" | "m",
+    setbacks: PluginBuildableEnvelopeSetbackTier[],
+    verticalCap: PluginBuildableEnvelopeVerticalCap,
+    floorToFloor: number,
+    farRatio?: number,
+    lotCoverageMaxPct?: number
+  ): PluginApiReturn<PluginBuildableEnvelopeCreateResult>
+
+  /**
+   * Update an existing parametric buildable envelope — regenerate the zoning
+   * volume from a revised site polygon, setbacks, vertical cap, or FAR and
+   * lot-coverage limits, keeping the same envelope id.
+   *
+   * Edge state is preserved, like the right panel: every edge's type
+   * (front/side/rear) is kept. For each type whose value changed (by more than
+   * 2 mm), the per-edge custom distances on edges of that type are cleared;
+   * custom distances on types whose value did not change are kept.
+   *
+   * @param buildableEnvelopeId - Existing envelope ID to update; non-empty and
+   *   must match an existing envelope on the canvas.
+   * @param sitePolygon - Site polygon vertices in `lengthUnit`; minimum 3 vertices.
+   * @param lengthUnit - Unit used by all length fields (`"ft" | "m"`).
+   * @param setbacks - Setback profile, ground tier first; minimum 1 tier.
+   * @param verticalCap - Maximum height or floor count.
+   * @param floorToFloor - Required floor-to-floor height in `lengthUnit`.
+   * @param farRatio - Optional FAR value, positive when provided.
+   * @param lotCoverageMaxPct - Optional lot coverage cap, `0..100`.
+   * @returns A {@linkcode PluginBuildableEnvelopeUpdateResult} with the
+   *   `buildableEnvelopeId` of the updated envelope and `clearedEdgeSetbacks`,
+   *   the `edgeIndex` of each edge that lost its custom distance (empty when
+   *   none). Tell the user about any cleared edges.
+   * @throws If validation fails, the envelope does not exist, or generation
+   *   produces no renderable geometry. Also throws `PRECONDITION_FAILED`
+   *   (`details.reason: "STALE_EDGE_SETTINGS"`, nothing changes) when the site
+   *   outline changed since the edge settings were made. Tell the user;
+   *   editing any edge on the canvas setback pills resets the edge settings
+   *   to the new outline (dropping the old ones), after which you can retry.
+   *
+   * @examplePrompt Change the envelope's height limit to 175 feet
+   * @examplePrompt Update the setbacks on the buildable envelope
+   * @examplePrompt Regenerate the zoning envelope with a new site boundary
+   * @examplePrompt Increase the FAR on the buildable volume
+   * @examplePrompt Modify the envelope to allow 15 storeys instead
+   *
+   * # Example
+   * ```ts
+   * const { buildableEnvelopeId } = await snaptrude.entity.buildableEnvelope.update(
+   *   existingId,
+   *   [
+   *     { x: 0, z: 0 },
+   *     { x: 100, z: 0 },
+   *     { x: 100, z: 80 },
+   *     { x: 0, z: 80 },
+   *   ],
+   *   "ft",
+   *   [{ aboveHeight: 0, front: 10, side: 5, rear: 10 }],
+   *   { kind: "max_height", maxHeight: 175 },
+   *   12,
+   * )
+   * ```
+   *
+   * @deprecated Use `design.update.buildableEnvelope`
+   */
+  public abstract update(
+    buildableEnvelopeId: string,
+    sitePolygon: PluginBuildableEnvelopePolygonVertex[],
+    lengthUnit: "ft" | "m",
+    setbacks: PluginBuildableEnvelopeSetbackTier[],
+    verticalCap: PluginBuildableEnvelopeVerticalCap,
+    floorToFloor: number,
+    farRatio?: number,
+    lotCoverageMaxPct?: number
+  ): PluginApiReturn<PluginBuildableEnvelopeUpdateResult>
+}
+
+/**
+ * Site polygon vertex in the request `lengthUnit`.
+ *
+ * Vertices may be passed as `{x, z}` objects or `[x, z]` tuples. Numeric
+ * values must be finite (no `NaN` or `±Infinity`).
+ */
+export const PluginBuildableEnvelopePolygonVertex = z.union([
+  z.object({ x: z.number().finite(), z: z.number().finite() }).strict(),
+  z.tuple([z.number().finite(), z.number().finite()]),
+])
+
+export type PluginBuildableEnvelopePolygonVertex = z.infer<
+  typeof PluginBuildableEnvelopePolygonVertex
+>
+
+/**
+ * Vertical cap for a buildable envelope.
+ *
+ * Use exactly one shape:
+ * - `{ kind: "max_height", maxHeight }`
+ * - `{ kind: "max_floors", maxFloors }`
+ *
+ * Floor-to-floor height is not nested here; it is always supplied as the
+ * top-level `floorToFloor` argument.
+ */
+export const PluginBuildableEnvelopeVerticalCap = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("max_height"),
+    maxHeight: z.number().finite().positive(),
+  }).strict(),
+  z.object({
+    kind: z.literal("max_floors"),
+    maxFloors: z.number().finite().int().positive(),
+  }).strict(),
+])
+
+export type PluginBuildableEnvelopeVerticalCap = z.infer<
+  typeof PluginBuildableEnvelopeVerticalCap
+>
+
+/**
+ * One tier of a buildable envelope's setback profile.
+ *
+ * Tiers are ordered by `aboveHeight`. The first tier (index 0) must have
+ * `aboveHeight: 0` and describes the ground footprint; each subsequent tier
+ * describes the complete setback at a strictly greater height. Each tier
+ * carries its own `front`, `side`, and `rear` values — there is no
+ * inheritance from earlier tiers.
+ *
+ * All numeric values must be finite and nonnegative, in the request
+ * `lengthUnit`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `aboveHeight` | `number` | Height at or above which this tier applies; the ground tier uses `0` |
+ * | `front` | `number` | Front setback for this tier |
+ * | `side` | `number` | Side setback for this tier |
+ * | `rear` | `number` | Rear setback for this tier |
+ */
+export const PluginBuildableEnvelopeSetbackTier = z.object({
+  aboveHeight: z.number().finite().nonnegative(),
+  front: z.number().finite().nonnegative(),
+  side: z.number().finite().nonnegative(),
+  rear: z.number().finite().nonnegative(),
+}).strict()
+
+export type PluginBuildableEnvelopeSetbackTier = z.infer<
+  typeof PluginBuildableEnvelopeSetbackTier
+>
+
+// Enforces setback tier ordering invariants on the parsed args shape:
+//   - setbacks[0].aboveHeight === 0
+//   - aboveHeight strictly increasing thereafter
+// Length >= 1 is enforced earlier by z.array(...).min(1).
+function refineSetbackTiers(
+  args: { setbacks: PluginBuildableEnvelopeSetbackTier[] },
+  ctx: z.RefinementCtx
+): void {
+  const tiers = args.setbacks
+  if (tiers.length === 0) return
+  if (tiers[0].aboveHeight !== 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["setbacks", 0, "aboveHeight"],
+      message: "Ground tier required: setbacks[0].aboveHeight must be 0.",
+    })
+  }
+  for (let i = 1; i < tiers.length; i++) {
+    if (!(tiers[i].aboveHeight > tiers[i - 1].aboveHeight)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["setbacks", i, "aboveHeight"],
+        message:
+          "Setback tiers must be ordered by strictly increasing aboveHeight.",
+      })
+    }
+  }
+}
+
+/**
+ * Arguments for {@linkcode PluginBuildableEnvelopeApi.create}.
+ *
+ * Strict schema. The host owns identity — no `buildableEnvelopeId` is accepted
+ * on create; the id is minted by the host and returned in
+ * {@linkcode PluginBuildableEnvelopeCreateResult}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sitePolygon` | {@linkcode PluginBuildableEnvelopePolygonVertex}`[]` | Site polygon vertices in `lengthUnit`; minimum 3 vertices |
+ * | `lengthUnit` | `"ft" \| "m"` | Unit used by all length fields |
+ * | `setbacks` | {@linkcode PluginBuildableEnvelopeSetbackTier}`[]` | Setback profile, ground tier first; minimum 1 tier |
+ * | `verticalCap` | {@linkcode PluginBuildableEnvelopeVerticalCap} | Maximum height or floor count |
+ * | `floorToFloor` | `number` | Required floor-to-floor height in `lengthUnit` |
+ * | `farRatio` | `number?` | Optional FAR value, positive when provided |
+ * | `lotCoverageMaxPct` | `number?` | Optional lot coverage cap, `0..100` |
+ */
+export const PluginBuildableEnvelopeCreateArgs = z
+  .object({
+    sitePolygon: z.array(PluginBuildableEnvelopePolygonVertex).min(3),
+    lengthUnit: z.union([z.literal("ft"), z.literal("m")]),
+    setbacks: z.array(PluginBuildableEnvelopeSetbackTier).min(1),
+    verticalCap: PluginBuildableEnvelopeVerticalCap,
+    floorToFloor: z.number().finite().positive(),
+    farRatio: z.number().finite().positive().optional(),
+    lotCoverageMaxPct: z.number().finite().min(0).max(100).optional(),
+  })
+  .strict()
+  .superRefine(refineSetbackTiers)
+
+export type PluginBuildableEnvelopeCreateArgs = z.infer<
+  typeof PluginBuildableEnvelopeCreateArgs
+>
+
+/**
+ * Result of {@linkcode PluginBuildableEnvelopeApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildableEnvelopeId` | `string` | Non-empty unique ID of the created buildable envelope |
+ */
+export const PluginBuildableEnvelopeCreateResult = z.object({
+  buildableEnvelopeId: z.string().min(1),
+}).strict()
+
+export type PluginBuildableEnvelopeCreateResult = z.infer<
+  typeof PluginBuildableEnvelopeCreateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginBuildableEnvelopeApi.update}.
+ *
+ * Strict schema. `buildableEnvelopeId` is required and identifies the prior
+ * envelope on the canvas to update.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildableEnvelopeId` | `string` | Existing envelope ID to update; non-empty |
+ * | `sitePolygon` | {@linkcode PluginBuildableEnvelopePolygonVertex}`[]` | Site polygon vertices in `lengthUnit`; minimum 3 vertices |
+ * | `lengthUnit` | `"ft" \| "m"` | Unit used by all length fields |
+ * | `setbacks` | {@linkcode PluginBuildableEnvelopeSetbackTier}`[]` | Setback profile, ground tier first; minimum 1 tier |
+ * | `verticalCap` | {@linkcode PluginBuildableEnvelopeVerticalCap} | Maximum height or floor count |
+ * | `floorToFloor` | `number` | Required floor-to-floor height in `lengthUnit` |
+ * | `farRatio` | `number?` | Optional FAR value, positive when provided |
+ * | `lotCoverageMaxPct` | `number?` | Optional lot coverage cap, `0..100` |
+ */
+export const PluginBuildableEnvelopeUpdateArgs = z
+  .object({
+    buildableEnvelopeId: z.string().min(1),
+    sitePolygon: z.array(PluginBuildableEnvelopePolygonVertex).min(3),
+    lengthUnit: z.union([z.literal("ft"), z.literal("m")]),
+    setbacks: z.array(PluginBuildableEnvelopeSetbackTier).min(1),
+    verticalCap: PluginBuildableEnvelopeVerticalCap,
+    floorToFloor: z.number().finite().positive(),
+    farRatio: z.number().finite().positive().optional(),
+    lotCoverageMaxPct: z.number().finite().min(0).max(100).optional(),
+  })
+  .strict()
+  .superRefine(refineSetbackTiers)
+
+export type PluginBuildableEnvelopeUpdateArgs = z.infer<
+  typeof PluginBuildableEnvelopeUpdateArgs
+>
+
+/**
+ * Result of {@linkcode PluginBuildableEnvelopeApi.update}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildableEnvelopeId` | `string` | Non-empty unique ID of the updated buildable envelope |
+ * | `clearedEdgeSetbacks` | `number[]` | `edgeIndex` of every edge whose own custom distance was cleared because its type's (front/side/rear) value changed; empty when none |
+ */
+export const PluginBuildableEnvelopeUpdateResult = z.object({
+  buildableEnvelopeId: z.string().min(1),
+  clearedEdgeSetbacks: z.array(z.number().int().nonnegative()),
+}).strict()
+
+export type PluginBuildableEnvelopeUpdateResult = z.infer<
+  typeof PluginBuildableEnvelopeUpdateResult
+>
+
+/**
+ * Patch for one site edge, as taken by `design.update.siteEdge`.
+ *
+ * Strict schema. Provide `role`, `setback`, or both. A numeric `setback`
+ * requires `lengthUnit`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `role` | `"front" \| "side" \| "rear"`? | New edge type. Setting it clears the edge's own distance |
+ * | `setback` | `number \| null`? | This edge's own setback distance in `lengthUnit` (finite, nonnegative); `null` clears it so the edge falls back to its type's distance |
+ * | `lengthUnit` | `"m" \| "ft"`? | Unit of `setback`; required when `setback` is a number |
+ */
+export const PluginSiteEdgePatch = z
+  .object({
+    role: PluginProgramSiteEdgeRole.optional(),
+    // null = clear this edge's own distance
+    setback: z.number().finite().nonnegative().nullable().optional(),
+    lengthUnit: z.enum(["m", "ft"]).optional(),
+  })
+  .strict()
+  .refine(
+    (p) => p.role !== undefined || p.setback !== undefined,
+    "patch must set role and/or setback"
+  )
+  .refine(
+    (p) => typeof p.setback !== "number" || p.lengthUnit !== undefined,
+    "lengthUnit is required with a numeric setback"
+  )
+
+export type PluginSiteEdgePatch = z.infer<typeof PluginSiteEdgePatch>
+
+/**
+ * Result of `design.update.siteEdge` — the refreshed edge entry for the
+ * site, exactly as `program.site.listEdges()` returns it.
+ */
+export const PluginDesignUpdateSiteEdgeResult = PluginProgramSiteEdgesEntry
+
+export type PluginDesignUpdateSiteEdgeResult = z.infer<
+  typeof PluginDesignUpdateSiteEdgeResult
+>
+
+/**
+ * Result of `design.create.buildableEnvelopeFromSite`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildableEnvelopeId` | `string` | ID of the created buildable envelope |
+ */
+export const PluginDesignCreateBuildableEnvelopeFromSiteResult = z
+  .object({
+    buildableEnvelopeId: z.string(),
+  })
+  .strict()
+
+export type PluginDesignCreateBuildableEnvelopeFromSiteResult = z.infer<
+  typeof PluginDesignCreateBuildableEnvelopeFromSiteResult
+>