Operation Contracts

Operation contracts define what an agent can safely call, what params are required, what paths are created, and which evals are affected.

plotParcel

Creates a parcel from boundary geometry.

Field	Value
targetPath	site.{site}.parcels
Required params	id, boundary
Optional params	coordinateSpace, source, metadata
Creates	site.{site}.parcels.{parcel}
Affects evals	parcel.boundary_closed, parcel.no_self_intersection, parcel.edge_classification_complete

{
  "type": "plotParcel",
  "targetPath": "site.main.parcels",
  "params": {
    "id": "pcl_001",
    "coordinateSpace": "site.main.frames.local",
    "boundary": {
      "unit": "mm",
      "edges": [
        { "id": "front", "from": [0, 0], "to": [42000, 0], "tags": ["frontage"] },
        { "id": "east", "from": [42000, 0], "to": [39000, 28000] },
        { "id": "rear", "from": [39000, 28000], "to": [4000, 31000] },
        { "id": "west", "from": [4000, 31000], "to": [0, 0] }
      ]
    }
  }
}

addPlanningRule

Adds a deterministic planning constraint to a parcel, site, envelope, or building.

Field	Value
targetPath	.constraints group
Required params	kind, rule-specific params
Optional params	id, authority, source, metadata
Creates	Constraint path under target constraints group
Affects evals	Planning evals matching rule kind

{
  "type": "addPlanningRule",
  "targetPath": "site.main.parcels.pcl_001.constraints.setbacks",
  "params": {
    "id": "front",
    "kind": "setback",
    "from": "boundary.edges.front",
    "distance": "5000mm"
  }
}

createTerrainSurface

Creates a terrain surface from points, contours, grid data, or an imported source.

Field	Value
targetPath	site.{site}.terrain
Required params	id, representation
Optional params	source, points, contours, breaklines, coordinateSpace
Creates	site.{site}.terrain.{surface}
Affects evals	terrain.valid_surface, terrain.slope_threshold, terrain.drainage_conflict

{
  "type": "createTerrainSurface",
  "targetPath": "site.main.terrain",
  "params": {
    "id": "existing",
    "representation": "contours",
    "source": "survey.existing_topo"
  }
}

computeBuildableEnvelope

Derives a buildable envelope from parcel geometry and constraints.

Field	Value
targetPath	site.{site}.parcels.{parcel}
Required params	rules
Optional params	outputPath, tolerance
Creates	site.{site}.envelopes.{envelope}
Affects evals	planning.setback_distance, planning.lot_coverage, planning.envelope_compliance

{
  "type": "computeBuildableEnvelope",
  "targetPath": "site.main.parcels.pcl_001",
  "params": {
    "rules": ["constraints.setbacks", "constraints.height_limit", "constraints.lot_coverage"],
    "outputPath": "site.main.envelopes.primary",
    "tolerance": { "linear": "5mm" }
  }
}

generateFloorplates

Generates floorplates inside an envelope or massing volume.

Field	Value
targetPath	buildings.{building}
Required params	envelope
Optional params	levels, floorToFloor, maxDepth, strategy, tolerance
Creates	buildings.{building}.levels.{level}.floorplate
Affects evals	building.footprint_inside_envelope, building.floorplate_efficiency, planning.far

{
  "type": "generateFloorplates",
  "targetPath": "buildings.b_001",
  "params": {
    "envelope": "site.main.envelopes.primary",
    "floorToFloor": "3100mm",
    "maxDepth": "14500mm",
    "strategy": "maximize_gfa"
  }
}

placeCore

Places or updates a building core.

Field	Value
targetPath	buildings.{building}.systems.core.{core}
Required params	strategy
Optional params	stairs, elevators, shafts, minClearances, tolerance
Creates	Core, stairs, elevators, shafts, and related relations
Affects evals	building.core_placement, building.egress_routes, building.service_shaft_continuity

{
  "type": "placeCore",
  "targetPath": "buildings.b_001.systems.core.main",
  "params": {
    "strategy": "central",
    "stairs": 2,
    "elevators": 2
  }
}

fitMassingToEnvelope

Repairs or adjusts massing so it fits an envelope.

Field	Value
targetPath	buildings.{building} or buildings.{building}.massing.{mass}
Required params	envelope
Optional params	preserveGfa, allowedMoves, tolerance
Creates	Updated massing and derived floorplate changes
Affects evals	planning.envelope_compliance, planning.lot_coverage, planning.far

{
  "type": "fitMassingToEnvelope",
  "targetPath": "buildings.b_001",
  "params": {
    "envelope": "site.main.envelopes.primary",
    "preserveGfa": false,
    "allowedMoves": ["shrink_footprint", "reduce_upper_levels"]
  }
}