Params

Params should be explicit, typed, and boring. Agents should not have to infer units, coordinate spaces, or positional argument meaning.

Rule

Every operation must document:

• targetPath
• Required params
• Optional params
• Units
• Coordinate-space behavior
• Created paths
• Affected evals
• Repair hints
• Backend export behavior

Good Param Shape

{
  "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"
    }
  }
}

Bad Param Shape

{
  "op": "envelope",
  "target": "pcl_001",
  "params": [5000, 18000, 0.4]
}

Arrays should not carry architectural meaning unless they are geometry tuples inside a declared coordinate space.

Required Param Primitives

Param primitive	Purpose	Example
Quantity	Unit-tagged scalar	"5000mm"
Ratio	Unitless ratio with semantic label	{ "value": 0.4 }
Angle	Angle with unit	"35deg"
Coordinate	Point in explicit coordinate space	{ "space": "site.main.frames.local", "x": "0mm", "y": "0mm" }
Vector	Direction and magnitude	{ "dx": "3000mm", "dy": "0mm" }
Transform	Mapping between coordinate spaces	{ "from": "...", "to": "...", "kind": "affine3d" }
BoundaryLoop	Closed boundary	edges or coordinates
Polyline	Ordered path geometry	contour, road, breakline
PolygonRegion	Region geometry	envelope, no-build area
TerrainSurface	Terrain representation	TIN, grid, contours, hybrid
ReferencePath	Canonical graph path	"site.main.envelopes.primary"
Selector	Set target	path("buildings.b_001.levels.*.floorplate")
RuleRef	Eval or planning rule reference	"planning.lot_coverage"
Tolerance	Numeric tolerance	{ "linear": "5mm", "angular": "0.1deg" }
Strategy	Named algorithm choice	{ "strategy": "central" }
Metadata	Extra typed metadata	{ "source": "survey_2026_05" }

Quantity

Quantities are serialized as unit-tagged strings or typed objects.

"5000mm"

{
  "value": 5000,
  "unit": "mm"
}

Canonical hashing should normalize equivalent values.

Coordinate

Coordinates must include or inherit a coordinate space.

{
  "space": "site.main.frames.local",
  "x": "0mm",
  "y": "42000mm",
  "z": "0mm"
}

Compact source syntax is allowed only in scoped geometry blocks:

boundary:
  coordinate_space site.main.frames.local
  unit mm
  edge front: (0, 0) -> (42000, 0)

ReferencePath

Paths are params too. Prefer paths over bare IDs in agent patches.

{
  "envelope": "site.main.envelopes.primary",
  "parcel": "site.main.parcels.pcl_001"
}

Tolerance

Every geometry-affecting operation should accept tolerances or inherit project defaults.

{
  "tolerance": {
    "linear": "5mm",
    "area": "0.01sqm",
    "angular": "0.1deg"
  }
}

Operation Param Documentation Template

operation: computeBuildableEnvelope
targetPath: site.{site}.parcels.{parcel}
required_params:
  rules: RuleRef[]
optional_params:
  outputPath: ReferencePath
  tolerance: Tolerance
coordinate_space:
  reads: target parcel boundary space
  writes: envelope in site local frame
created_paths:
  site.{site}.envelopes.{name}
affected_evals:
  planning.setback_distance
  planning.lot_coverage
  planning.envelope_compliance