feat: iris_build_constraints — map IRIS build version to known runtime limitations

[isc-tdyar]

Problem

IRIS build-specific bugs are invisible until you hit them. There's no way for an agent to proactively know "in build 161, embedded Python SQL column resolution on class-projected tables is broken" before writing code that depends on it. This creates debugging sessions that are essentially archaeology.

Proposed Tool: iris_build_constraints

iris_build_constraints()

Returns constraints for the currently connected IRIS instance:

{
  "build": "2026.2.0AI.161",
  "constraints": [
    {
      "id": "ddtab_column_resolution",
      "severity": "error",
      "description": "Column resolution on class-projected tables fails in embedded Python SQL context",
      "affected_since": "161",
      "fixed_in": "162",
      "workaround": "Use direct global access or external SQL via Atelier REST"
    },
    {
      "id": "iris_sql_prepare_vector",
      "severity": "warning",
      "description": "VECTOR column type not supported in prepared statements via iris.sql",
      "affected_since": "158",
      "fixed_in": null,
      "workaround": "Use string interpolation (with sanitization) or native API"
    }
  ],
  "known_good": ["external_sql", "objectscript_execution", "global_access"]
}

Implementation Notes

• Constraints DB is a static JSON file bundled with iris-dev, keyed by build version range
• Updated as bugs are discovered/fixed (community-contributed)
• iris_build_constraints reads check_config to get current build, then looks up the constraints table
• Could also be called as iris_build_constraints("2026.2.0AI.161") to check a specific build

Value

The most proactive of the four proposed tools — converts debugging knowledge into prevention. An agent that calls this at session start can avoid entire classes of bugs by choosing the right execution path from the beginning.

Related

• feat: iris_table_info — DDL vs class-projection detection with global layout #38 iris_table_info — accessible_from_embedded_python flag driven by this constraints DB
• feat: iris_validate_embedded_sql — check SQL compatibility in embedded Python context #39 iris_validate_embedded_sql — uses this to explain failures