@snaptrude/plugin-core 0.9.16-networks-20261012.1 → 0.9.17

package/src/api/design/networks.ts

@@ -1,607 +0,0 @@
-import * as z from "zod"
-import type { PluginApiReturn } from "../../types"
-
-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()
-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: 1
-  requestId: string
-  document: NetworkGraphDocument
-  components: NetworkComponentBinding[]
-}
-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 {}
-/** Family-backed air-side HVAC networks. The agent authors engineering intent; the host constructs it. */
-export abstract class PluginMechanicalApi extends PluginDomainNetworkApi {}

package/src/api/presentation/drawingContract.ts

@@ -1,70 +0,0 @@
-import * as z from "zod"
-
-/**
- * Metric architectural scale denominators (`100` means 1:100), the metric
- * values of the placed view's Scale dropdown.
- */
-export const METRIC_DRAWING_SCALES = [
-  10, 20, 50, 100, 150, 200, 250, 500, 1000,
-] as const
-
-/**
- * Imperial detail scale denominators, 1" = 1' (12) to 1/128" = 1' (1536):
- * `48` is 1/4" = 1', `96` is 1/8" = 1'.
- */
-export const IMPERIAL_DETAIL_DRAWING_SCALES = [
-  12, 16, 24, 32, 48, 64, 96, 128, 192, 384, 768, 1536,
-] as const
-
-/** Imperial site (engineering) scale denominators, 1" = 10' (120) to 1" = 400' (4800). */
-export const IMPERIAL_SITE_DRAWING_SCALES = [
-  120, 240, 360, 480, 600, 1200, 2400, 3600, 4800,
-] as const
-
-/**
- * Imperial architectural scale denominators, ascending: the imperial detail
- * and site values of the placed view's Scale dropdown.
- */
-export const IMPERIAL_DRAWING_SCALES: readonly number[] = [
-  ...IMPERIAL_DETAIL_DRAWING_SCALES,
-  ...IMPERIAL_SITE_DRAWING_SCALES,
-].sort((a, b) => a - b)
-
-/**
- * Every standard architectural scale denominator, metric and imperial,
- * ascending. Drawing and placed-view scale arguments accept only these; the
- * host may further restrict them to the project's unit system.
- */
-export const STANDARD_DRAWING_SCALES: readonly number[] = [
-  ...METRIC_DRAWING_SCALES,
-  ...IMPERIAL_DRAWING_SCALES,
-].sort((a, b) => a - b)
-
-const standardScaleSet = new Set<number>(STANDARD_DRAWING_SCALES)
-
-/** A standard architectural scale denominator; anything else is rejected with the allowed list. */
-export const PluginStandardDrawingScale = z
-  .number()
-  .finite()
-  .refine((scale) => standardScaleSet.has(scale), {
-    message: `Scale must be a standard architectural scale denominator in the project's unit system. Metric: ${METRIC_DRAWING_SCALES.join(", ")}; imperial detail: ${IMPERIAL_DETAIL_DRAWING_SCALES.join(", ")}; imperial site: ${IMPERIAL_SITE_DRAWING_SCALES.join(", ")}. Pick the largest standard scale (smallest denominator) at which the view fits its frame or sheet and its room labels stay readable (usually 1:50 to 1:200 for a building plan).`,
-  })
-
-const EXTENSION = /\.(pdf|svg|png|jpe?g)$/i
-// The host appends ".<ext>", so a trailing dot yields "a.pdf..pdf" and trailing
-// whitespace yields "plan .pdf".
-const TRAILING_DOT_OR_SPACE = /[.\s]$/
-
-/**
- * An export base file name without an extension, not ending in a dot or
- * whitespace; the host adds `.pdf`, `.svg`, `.png` or `.jpg`.
- */
-export const PluginExportFileName = z
-  .string()
-  .refine(
-    (name) => !EXTENSION.test(name.trim()) && !TRAILING_DOT_OR_SPACE.test(name),
-    {
-      message:
-        "fileName must be a base name without an extension and not ending in a dot or a space (for example \"Ground Floor Plan\", not \"Ground Floor Plan.pdf\" or \"Ground Floor Plan.\"); the export adds the extension for the format.",
-    },
-  )