@snaptrude/plugin-core 0.9.16 → 0.9.18-networks-20261016.1

package/src/api/design/networks.ts

@@ -0,0 +1,667 @@
+import * as z from "zod"
+import type { PluginApiReturn } from "../../types"
+import { Vec3Handle } from "../../handles"
+
+const id = z.string().regex(/^[A-Za-z][A-Za-z0-9_-]{0,79}$/)
+const vector = z.tuple([
+  z.number().finite(),
+  z.number().finite(),
+  z.number().finite(),
+])
+const positive = z.number().finite().positive()
+const endpoint = z.object({ node: id, port: id }).strict()
+const relationships = z
+  .array(
+    z
+      .object({
+        node: id,
+        relation: z.enum(["mountedOn", "within", "serves", "penetrates"]),
+        target: z
+          .object({
+            kind: z.enum(["component", "topology"]),
+            id: z.string().min(1).max(200),
+          })
+          .strict(),
+      })
+      .strict(),
+  )
+  .max(4000)
+
+/** Versioned metadata stored in a pinned FamilySpecBundle.network. Expressions use the
+ * family's parameter scope and SU, just like its geometry. No world-space port overrides.
+ * Pipe recipes run from local [0,0,0] to [length,0,0] along +X.
+ */
+export const NetworkFamilyContract = z
+  .object({
+    schemaVersion: z.literal(1),
+    role: z.enum([
+      "pipe",
+      "duct",
+      "wire",
+      "cable",
+      "conduit",
+      "cableDuct",
+      "cableTray",
+      "connector",
+      "equipment",
+    ]),
+    lengthParameter: z.string().min(1).optional(),
+    ports: z
+      .array(
+        z
+          .object({
+            id,
+            position: z.tuple([z.string(), z.string(), z.string()]),
+            direction: z.tuple([z.string(), z.string(), z.string()]),
+            size: z.string(),
+            height: z.string().optional(),
+            /** Unit width axis in family coordinates, perpendicular to direction.
+             * Required with height for mechanical rectangular ports; prevents guessed roll.
+             */
+            widthDirection: z
+              .tuple([z.string(), z.string(), z.string()])
+              .optional(),
+            systems: z.array(z.string().min(1)).min(1),
+          })
+          .strict(),
+      )
+      .min(1)
+      .max(64),
+  })
+  .strict()
+export type NetworkFamilyContract = z.infer<typeof NetworkFamilyContract>
+
+const familyPin = z
+  .object({
+    definitionId: z.string().min(1).max(200),
+    version: z.number().int().positive(),
+    values: z.record(
+      z.string(),
+      z.union([z.number().finite(), z.string(), z.boolean()]),
+    ),
+  })
+  .strict()
+
+/** Authored topology: vertices are pinned connector/equipment families; each edge is one
+ * line and one pinned straight-pipe family. Curved runs are not yet supported by this
+ * contract; bends require explicit connector vertices. World mm, Y up, rotations in degrees.
+ * Plumbing v2 accepts round ports only. Rectangular ports need a section-roll contract.
+ * The resolved component graph is retained for existing persistence, replay and queries.
+ */
+export const NetworkTopologyDocument = z
+  .object({
+    schemaVersion: z.literal(2),
+    domain: z.literal("plumbing"),
+    label: z.string().min(1).max(120),
+    architectureRevision: z.string().min(1).max(80),
+    relationships,
+    vertices: z
+      .array(
+        z
+          .object({
+            id,
+            kind: z.enum([
+              "fixture",
+              "equipment",
+              "tank",
+              "pump",
+              "valve",
+              "manifold",
+              "fitting",
+            ]),
+            storey: z.number().int(),
+            family: familyPin,
+            positionMm: vector,
+            rotationDeg: vector,
+            systems: z.record(z.string(), z.string().min(1)),
+          })
+          .strict(),
+      )
+      .min(1)
+      .max(1000),
+    edges: z
+      .array(
+        z
+          .object({
+            id,
+            kind: z.enum(["pipe", "riser"]),
+            storey: z.number().int(),
+            family: familyPin,
+            from: endpoint,
+            to: endpoint,
+            system: z.string().min(1),
+            /** One line between evaluated connector ports, never a corner-bearing polyline. */
+            curve: z.object({ kind: z.literal("line") }).strict(),
+          })
+          .strict(),
+      )
+      .max(1000),
+  })
+  .strict()
+export type NetworkTopologyDocument = z.infer<typeof NetworkTopologyDocument>
+
+export const MechanicalAirSystem = z.enum([
+  "supplyAir",
+  "returnAir",
+  "exhaustAir",
+  "outsideAir",
+  "reliefAir",
+])
+const mechanicalVertexKind = z.enum([
+  "equipment",
+  "terminal",
+  "damper",
+  "fitting",
+])
+const mechanicalEdgeKind = z.enum(["duct", "riser"])
+
+/** Air-side HVAC intent. Reuses the graph transport, not plumbing domain semantics.
+ * Every vertex and edge pins an existing family. Edges run from upstream to downstream.
+ * Rectangular duct ports use local +Y as their width axis. The host aligns this axis to
+ * the upstream connector's widthDirection and rejects incompatible downstream roll.
+ * Bends, branches and transitions are explicit fitting vertices. No flexible curves,
+ * hydronic/refrigerant design, airflow sizing or code-compliance inference is provided.
+ */
+export const MechanicalTopologyDocument = NetworkTopologyDocument.extend({
+  domain: z.literal("mechanical"),
+  vertices: z
+    .array(
+      NetworkTopologyDocument.shape.vertices.element.extend({
+        kind: mechanicalVertexKind,
+        systems: z.record(z.string(), MechanicalAirSystem),
+      }),
+    )
+    .min(1)
+    .max(1000),
+  edges: z
+    .array(
+      NetworkTopologyDocument.shape.edges.element.extend({
+        kind: mechanicalEdgeKind,
+        system: MechanicalAirSystem,
+      }),
+    )
+    .max(1000),
+})
+export type MechanicalTopologyDocument = z.infer<
+  typeof MechanicalTopologyDocument
+>
+
+const electricalVertexKind = z.enum([
+  "transformer",
+  "mainBoard",
+  "distributionBoard",
+  "mcbBox",
+  "junctionBox",
+  "switch",
+  "outlet",
+  "light",
+  "load",
+  "equipment",
+  "fitting",
+])
+const electricalEdgeKind = z.enum([
+  "wire",
+  "cable",
+  "conduit",
+  "cableDuct",
+  "cableTray",
+])
+const electricalCircuits = z
+  .array(
+    z
+      .object({
+        id,
+        source: id,
+        loads: z.array(id).min(1).max(1000),
+        routes: z.array(id).max(1000),
+        voltage: positive,
+        phases: z.number().int().min(1).max(3),
+        ratedAmps: positive,
+      })
+      .strict(),
+  )
+  .max(1000)
+
+/** Physical electrical topology, independent of logical circuit membership.
+ * Each straight edge pins a family whose role matches its kind. Bends and branches
+ * require connector vertices. Junction boxes are equipment with explicit named ports.
+ * Rectangular containment uses the same section frame as mechanical ducts.
+ * Systems are authored labels which must be supported by the pinned ports.
+ * Direction is explicit, never inferred from circuits or spatial contact.
+ */
+export const ElectricalTopologyDocument = NetworkTopologyDocument.extend({
+  domain: z.literal("electrical"),
+  vertices: z
+    .array(
+      NetworkTopologyDocument.shape.vertices.element.extend({
+        kind: electricalVertexKind,
+      }),
+    )
+    .min(1)
+    .max(1000),
+  edges: z
+    .array(
+      NetworkTopologyDocument.shape.edges.element.extend({
+        kind: electricalEdgeKind,
+        directed: z.boolean(),
+      }),
+    )
+    .max(1000),
+  circuits: electricalCircuits,
+})
+export type ElectricalTopologyDocument = z.infer<
+  typeof ElectricalTopologyDocument
+>
+
+export const AuthoredNetworkTopologyDocument = z.discriminatedUnion("domain", [
+  NetworkTopologyDocument,
+  MechanicalTopologyDocument,
+  ElectricalTopologyDocument,
+])
+export type AuthoredNetworkTopologyDocument = z.infer<
+  typeof AuthoredNetworkTopologyDocument
+>
+
+/** Authored world-space connector. This is not a claim of certified family connector metadata. */
+export const NetworkPort = z
+  .object({
+    id,
+    positionMm: vector,
+    direction: vector,
+    system: z.string().min(1).max(80),
+    /** Diameter for round ports; width when heightMm is supplied (rectangular port). */
+    sizeMm: positive,
+    heightMm: positive.optional(),
+    /** World-space unit width axis. Mechanical rectangular ports require this section frame. */
+    widthDirection: vector.optional(),
+  })
+  .strict()
+
+/** The agent supplies every route and section. The host does not size or route a network. */
+export const NetworkGeometry = z.discriminatedUnion("kind", [
+  z
+    .object({
+      kind: z.literal("family"),
+      definitionId: z.string().min(1).max(200),
+      version: z.number().int().positive(),
+      values: z.record(
+        z.string(),
+        z.union([z.number().finite(), z.string(), z.boolean()]),
+      ),
+      positionMm: vector,
+      rotationDeg: vector,
+      ports: z.array(NetworkPort).max(64),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("route"),
+      pathMm: z.array(vector).min(2).max(256),
+      system: z.string().min(1).max(80),
+      section: z.discriminatedUnion("kind", [
+        z
+          .object({
+            kind: z.literal("round"),
+            diameterMm: positive,
+            wallMm: z.number().finite().nonnegative(),
+          })
+          .strict(),
+        z
+          .object({
+            kind: z.literal("rectangular"),
+            widthMm: positive,
+            heightMm: positive,
+            wallMm: z.number().finite().nonnegative(),
+          })
+          .strict(),
+      ]),
+    })
+    .strict(),
+])
+
+// Storey is scene membership, not a coordinate offset. A route can span multiple elevations.
+const node = z
+  .object({ id, storey: z.number().int(), geometry: NetworkGeometry })
+  .strict()
+const electricalNode = node.extend({
+  kind: z.enum([
+    ...electricalVertexKind.options,
+    ...electricalEdgeKind.options,
+  ]),
+})
+const plumbingNode = node.extend({
+  kind: z.enum([
+    "fixture",
+    "equipment",
+    "tank",
+    "pump",
+    "valve",
+    "manifold",
+    "fitting",
+    "pipe",
+    "riser",
+  ]),
+})
+const document = z
+  .object({
+    schemaVersion: z.literal(1),
+    label: z.string().min(1).max(120),
+    /** Revision from context(); invalidated when the source architectural graph changes. */
+    architectureRevision: z.string().min(1).max(80),
+    connections: z
+      .array(
+        z
+          .object({ id, from: endpoint, to: endpoint, directed: z.boolean() })
+          .strict(),
+      )
+      .max(4000),
+    relationships,
+  })
+  .strict()
+
+/** Electrical connectivity and circuit membership are distinct from physical route occupancy. */
+export const ElectricalGraphDocument = document.extend({
+  domain: z.literal("electrical"),
+  nodes: z.array(electricalNode).min(1).max(1000),
+  circuits: electricalCircuits,
+  /** Required for new authoring. Omitted only on saved legacy snapshots. */
+  authored: ElectricalTopologyDocument.optional(),
+})
+
+/** Plumbing uses explicit directed port connections; touching geometry never creates a connection. */
+export const PlumbingGraphDocument = document.extend({
+  domain: z.literal("plumbing"),
+  nodes: z.array(plumbingNode).min(1).max(1000),
+  /** Original v2 intent. Nodes/connections are the resolved snapshot for replay.
+   * Kept inside the document so existing save services preserve it without envelope changes.
+   * Legacy v1 saves omit this field; new plumbing submissions require v2.
+   */
+  authored: NetworkTopologyDocument.optional(),
+})
+/** Resolved HVAC snapshot for queries, commands and load. New submissions require v2 intent. */
+export const MechanicalGraphDocument = document.extend({
+  domain: z.literal("mechanical"),
+  nodes: z
+    .array(
+      node.extend({
+        kind: z.enum([
+          ...mechanicalVertexKind.options,
+          ...mechanicalEdgeKind.options,
+        ]),
+        geometry: NetworkGeometry.options[0],
+      }),
+    )
+    .min(1)
+    .max(1000),
+  authored: MechanicalTopologyDocument,
+})
+export const NetworkGraphDocument = z.discriminatedUnion("domain", [
+  ElectricalGraphDocument,
+  PlumbingGraphDocument,
+  MechanicalGraphDocument,
+])
+export type NetworkGraphDocument = z.infer<typeof NetworkGraphDocument>
+export type NetworkNode = NetworkGraphDocument["nodes"][number]
+export type NetworkPort = z.infer<typeof NetworkPort>
+export type NetworkDomain = NetworkGraphDocument["domain"]
+
+/** JSON is an authored document, not a transport for live geometry handles. Maximum 2 MB characters. */
+export const NetworkValidateArgs = z
+  .object({ graphJson: z.string().max(2_000_000) })
+  .strict()
+export const NetworkCreateArgs = NetworkValidateArgs.extend({
+  requestId: z.string().uuid(),
+})
+export const NetworkGetArgs = z.object({ graphId: z.string().uuid() }).strict()
+/** Displacement components are world millimetres, Y up, not Snaptrude units. */
+export const NetworkMoveEdgeArgs = NetworkGetArgs.extend({
+  expectedRevision: z.number().int().positive(),
+  edgeId: id,
+  displacement: Vec3Handle,
+  requestId: z.string().uuid(),
+}).strict()
+export type NetworkMoveEdgeArgs = z.input<typeof NetworkMoveEdgeArgs>
+
+export const NetworkMoveEdgeResult = z.object({
+  graphId: z.string().uuid(),
+  revision: z.number().int().positive(),
+  affectedComponentIds: z.array(z.string().min(1)),
+  alreadyApplied: z.boolean(),
+  /** Queue acceptance does not acknowledge durable storage. */
+  saveStatus: z.enum(["queued", "existing"]),
+}).strict()
+export type NetworkMoveEdgeResult = z.infer<typeof NetworkMoveEdgeResult>
+
+/** Immutable receipts survive undo. Retrying a move never executes it again. */
+export const NetworkEditReceipt = z.object({
+  requestId: z.string().uuid(),
+  fingerprint: z.string().max(1000),
+  revision: z.number().int().positive(),
+  affectedComponentIds: z.array(z.string().min(1)).max(1000),
+}).strict()
+export type NetworkEditReceipt = z.infer<typeof NetworkEditReceipt>
+
+/** Each intentional apply/undo/redo has its own identity. Retries reuse it. */
+export const NetworkTransition = z.object({
+  id: z.string().uuid(),
+  expectedRevision: z.number().int().positive(),
+  forward: z.boolean(),
+}).strict()
+export type NetworkTransition = z.infer<typeof NetworkTransition>
+
+export const NetworkTransitionReceipt = NetworkTransition.extend({
+  requestId: z.string().uuid(),
+  revision: z.number().int().positive(),
+}).strict()
+export type NetworkTransitionReceipt = z.infer<typeof NetworkTransitionReceipt>
+export const NetworkContextArgs = z
+  .object({
+    offset: z.number().int().nonnegative().default(0),
+    limit: z.number().int().min(1).max(100).default(30),
+    /** Omit the legacy PG2 dump when using the routing view, to avoid duplicate geometry tokens. */
+    includeTopology: z.boolean().default(true),
+  })
+  .strict()
+export const NetworkQueryArgs = NetworkGetArgs.extend({
+  revision: z.number().int().positive(),
+  queryJson: z.string().max(16000),
+})
+export const NetworkQuery = z
+  .object({
+    kind: z.enum([
+      "nodes",
+      "connected",
+      "upstream",
+      "downstream",
+      "ports",
+      "nearestPort",
+      "circuits",
+      "relationships",
+    ]),
+    node: id.optional(),
+    pointMm: vector.optional(),
+    radiusMm: positive.optional(),
+    /** Filter nodes, ports and traversal links by system. Traversal always includes its start node. */
+    system: z.string().optional(),
+    sizeMm: positive.optional(),
+    heightMm: positive.optional(),
+    offset: z.number().int().nonnegative().default(0),
+    limit: z.number().int().min(1).max(100).default(30),
+  })
+  .strict()
+export type NetworkQuery = z.infer<typeof NetworkQuery>
+
+export interface NetworkDiagnostic {
+  path: string
+  message: string
+}
+export interface NetworkValidation {
+  ok: boolean
+  diagnostics: NetworkDiagnostic[]
+  nodeCount: number
+}
+/** Durable node-to-scene mapping. New family-backed nodes retain the original authorized pin;
+ * parameters and placement belong to the component, not a generated library family.
+ * Existing wrapper pins and v1 raw-route recipe pins remain readable, not newly authored.
+ */
+export const NetworkComponentBinding = z
+  .object({
+    nodeId: id,
+    componentId: z.string().min(1),
+    definitionId: z.string().min(1),
+    definitionVersion: z.number().int().positive(),
+  })
+  .strict()
+export type NetworkComponentBinding = z.infer<typeof NetworkComponentBinding>
+export interface SavedNetworkGraph {
+  id: string
+  domain: NetworkDomain
+  revision: number
+  requestId: string
+  document: NetworkGraphDocument
+  components: NetworkComponentBinding[]
+  edits?: NetworkEditReceipt[]
+  transitions?: NetworkTransitionReceipt[]
+}
+export interface NetworkCreateResult {
+  graphId: string
+  revision: number
+  components: NetworkComponentBinding[]
+  alreadyCreated: boolean
+  /** Queue acceptance is not a durable database acknowledgement. */
+  saveStatus: "queued" | "existing"
+}
+
+/** Exact TopoGraph routing evidence, not a route planner or inferred enclosure.
+ * World mm, Y-up. A curve's axis is a unit direction, not a length.
+ * Shared region IDs mean a shared boundary, not permission to penetrate a wall.
+ * Regions preserve directed outer/hole loops. No vertical connectivity is inferred;
+ * use their curves and storey elevations to plan risers and explicit penetrations.
+ */
+export interface NetworkRoutingContext {
+  units: "mm"
+  edges: {
+    id: string
+    curve:
+      | { type: "line"; start: number[]; end: number[] }
+      | {
+          type: "arc"
+          start: number[]
+          end: number[]
+          centre: number[]
+          axis: number[]
+        }
+    wallId: string | null
+    regionIds: string[]
+  }[]
+  regions: {
+    id: string
+    /** Stable source component IDs; read label/storey from context.components. */
+    ownerIds: string[]
+    boundary: {
+      outer: { edgeId: string; direction: "forward" | "reverse" }[]
+      holes: { edgeId: string; direction: "forward" | "reverse" }[][]
+    }
+    floorId: string | null
+    slabId: string | null
+  }[]
+  /** Hosting is exact; bounds are only coarse avoidance data, not a penetration clearance check. */
+  openings: {
+    id: string
+    wallId: string
+    type: string
+    minMm: number[]
+    maxMm: number[]
+  }[]
+}
+export interface NetworkContextResult {
+  proposalId: string
+  buildingId: string | null
+  revision: string
+  /** PG2's native serialization uses Snaptrude units (1 SU = 254 mm). */
+  topologyUnits: "SU"
+  /** JSON array; empty when includeTopology is false. Prefer routing for network planning. */
+  topologyJson: string
+  /** Each collection uses offset/limit independently. Follow nextOffset before resolving references.
+   * Empty regions mean topology is unavailable, not that bounds can substitute for room boundaries.
+   */
+  routing: NetworkRoutingContext
+  nextOffset: number | null
+  total: number
+  storeys: { number: number; elevationMm: number }[]
+  components: {
+    id: string
+    type: string
+    label: string
+    storey: number
+    minMm: number[]
+    maxMm: number[]
+  }[]
+  /** Saved graph inventory, paged with topology/components. Use these IDs after reopening a project. */
+  networks: {
+    graphId: string
+    domain: NetworkDomain
+    revision: number
+    label: string
+    componentCount: number
+  }[]
+}
+export interface NetworkQueryResult {
+  revision: number
+  resultJson: string
+  nextOffset: number | null
+  total: number
+}
+
+/** Shared transport only. Each domain retains a separate schema and semantics. */
+export abstract class PluginDomainNetworkApi {
+  /** Read the active proposal's architectural context before authoring. Keep one revision across pages. */
+  abstract context(
+    args?: z.input<typeof NetworkContextArgs>,
+  ): PluginApiReturn<NetworkContextResult>
+  /** Validate authored JSON, pinned families and recipe evaluation without placing or saving anything.
+   * This does not build kernel meshes or certify engineering/code compliance.
+   */
+  abstract validate(
+    args: z.input<typeof NetworkValidateArgs>,
+  ): PluginApiReturn<NetworkValidation>
+  /** Construct each node on its authored storey, with one undo command and queued project persistence.
+   * Networks can span storeys. Reuse requestId on retry; components returns the durable node mapping.
+   * Coordinates are world millimetres, Y-up; rotations are degrees. No engineering rules are inferred.
+   * Throws for stale architecture, invalid references/geometry or conflicting retries.
+   */
+  abstract create(
+    args: z.input<typeof NetworkCreateArgs>,
+  ): PluginApiReturn<NetworkCreateResult>
+  /** Read one saved graph in the active proposal; null on miss. IDs are durable, not worker handles. */
+  abstract get(
+    args: z.input<typeof NetworkGetArgs>,
+  ): PluginApiReturn<SavedNetworkGraph | null>
+  /** Read bounded authored topology in graph revision. Crossings do not connect. No clash/compliance claims. */
+  abstract query(
+    args: z.input<typeof NetworkQueryArgs>,
+  ): PluginApiReturn<NetworkQueryResult>
+}
+
+/** Electrical equipment, physical routes and logical circuits, constructed from agent-authored intent. */
+export abstract class PluginElectricalApi extends PluginDomainNetworkApi {}
+/** Plumbing equipment and routed pipe networks, constructed from agent-authored intent. */
+export abstract class PluginPlumbingApi extends PluginDomainNetworkApi {
+  /** Offset one straight pipe perpendicular to its axis between two rigid 90-degree elbows.
+   * Resize adjacent pipes through instance length parameters. Out-of-plane offsets add
+   * one pinned elbow and straight pipe per affected end, preserving fixed outer ports
+   * and existing component identities. Rigid fittings only rotate and translate.
+   * Reject axial sliding, moving tees, constrained fittings,
+   * scene drift, stale revisions, and infeasible family geometry before mutation.
+   * @param args Graph/edge identity, current revision, displacement handle in world mm,
+   * and a unique retry identity. Identical retries return the original receipt after undo too.
+   * @returns Affected component IDs and revision in one undoable, queued transaction.
+   * @example
+   * const displacement = await snaptrude.core.math.vec3.new(0, 300, 0)
+   * await snaptrude.design.plumbing.moveEdge({ graphId, edgeId, expectedRevision,
+   *   displacement, requestId: crypto.randomUUID() })
+   */
+  abstract moveEdge(args: NetworkMoveEdgeArgs): PluginApiReturn<NetworkMoveEdgeResult>
+}
+/** Family-backed air-side HVAC networks. The agent authors engineering intent; the host constructs it. */
+export abstract class PluginMechanicalApi extends PluginDomainNetworkApi {}