Engineering IR

EngineeringOS requires a canonical intermediate representation because neither natural language nor author-facing DSL is sufficient as the stable computational core of the system. The IR is the layer where engineering meaning becomes explicit, structured, and durable enough to survive transformation, validation, versioning, and rendering across many targets. This chapter explains why the IR exists, how it relates to the ontology and language layers, and why it must remain distinct from any single file format or UI model.

Why IR Exists

Engineering IR exists to provide a stable execution boundary between human-facing inputs and machine-facing outputs. Natural language is too ambiguous, and Engineering Language is too author-oriented, to serve directly as the system's long-term computational contract. The IR is where engineering intent becomes explicit enough for validation, derivation, diffing, merging, and compilation.

This layer is also what allows EngineeringOS to support multiple authoring surfaces without multiplying compiler logic. Different editors, importers, or AI-assisted flows can all lower into the same IR if they preserve the same semantics. The result is one canonical model beneath many input experiences.

IR Versus DSL

Engineering Language is for writing and reading intent. Engineering IR is for preserving and transforming intent canonically. The distinction is structural, not cosmetic. A DSL can optimize for readability, authoring ergonomics, or domain idioms, while the IR must optimize for explicitness, completeness, and compiler stability.

The IR must therefore remain distinct from any one DSL syntax. Multiple surface languages may eventually target the same representation, and the same project may move between natural language generation, structured language authoring, and imported data. If the IR collapses into a single DSL or parser shape, the architecture loses the independence it needs to remain durable.

Canonical Representation

The canonical representation should encode the things the platform actually needs to reason about: identities, typed entities, relationships, constraints, behavior references, provenance, and extension points aligned with the Engineering Ontology. It should preserve meaning that downstream passes and targets depend on, not merely store whichever syntax happened to be used at authoring time.

That is why Engineering IR is closer to a semantic graph or typed model than to a document transcript. It is the place where relationships are first-class, where constraints are explicit, and where hidden assumptions are surfaced into structured form. A canonical IR is not valuable because it looks elegant. It is valuable because it makes semantic equivalence and compiler behavior testable.

IR Is Not Layout Or Geometry

One of the most important architectural boundaries in EngineeringOS is that Engineering IR must not collapse into either layout intent or geometry. Most existing engineering tools mix engineering meaning, presentation decisions, and rendering artifacts into one project structure. That makes synchronization brittle, automation shallow, and semantic reasoning dependent on coordinates and drawing conventions.

EngineeringOS should separate these concerns explicitly.

Engineering Intent
        ->
Semantic Model
        ->
Presentation / Layout Model
        ->
Geometry Model

These layers serve different purposes. Engineering IR describes what the system is: devices, functions, constraints, signals, relationships, and identities. A layout model describes how humans want to see that system: grouping, relative placement, flow, cabinet organization, alignment, and view-specific arrangement. A geometry model describes the final rendered form: coordinates, paths, symbols, splines, polygons, and exact graphical placement.

That separation is not cosmetic. It is what allows one semantic model to support multiple synchronized views, multiple downstream targets, and stable regeneration without making the drawing the source of truth again.

Identity And Stability

Stable identity is one of the main reasons the IR must exist at all. Devices, functions, connections, and other engineering objects need identifiers that survive page moves, renumbering, layout changes, and target regeneration. If identity is tied to coordinates, drawing order, or exporter-specific handles, then diffing and synchronization become fragile immediately.

Engineering IR should therefore preserve stable object identity and explicit references between objects. That stability enables semantic diff and merge, repeatable compiler passes, and reliable regeneration across many targets. It also makes change history more meaningful because the system can track what changed in engineering terms rather than only what changed in a text file.

This is also why layout changes must not redefine engineering identity. Moving a motor to another page, regrouping devices in a cabinet view, or choosing a different presentation scheme should not produce a new engineering object. The semantic model remains stable while views and renderers change around it.

Serialization And Compatibility

The IR may be serialized in several ways over time, but no serialization should be mistaken for the IR itself. JSON, binary formats, database layouts, and transport schemas are compatibility surfaces, not the conceptual definition of the representation. EngineeringOS should be able to evolve storage and exchange mechanisms without redefining the semantic model each time.

Compatibility should therefore be managed at the level of schema evolution, versioned adapters, and explicit upgrade paths. When the platform needs to change Engineering IR, it should do so as a governed architectural decision tied to ontology and compiler contracts, not as an accidental consequence of a new UI or exporter.

This boundary is especially important when the platform interacts with established standards such as AutomationML. EngineeringOS should learn from those standards and interoperate with them, but it should not allow their serialization formats or runtime assumptions to become the internal definition of the IR. A format such as AutomationML may appear on both sides of the compiler as an importer and an exporter, but it should never replace the semantic center of the platform.

Natural Language
DSL
AutomationML
        ->
Engineering IR
        ->
AutomationML
EPLAN
KiCad
QElectroTech
SVG

That is the correct ownership boundary. External standards are adapters and compatibility surfaces. Engineering IR remains the native semantic contract.

Role In The Compiler Pipeline

Engineering IR is the working substrate of the Engineering Compiler. Parsers, importers, and AI-assisted authoring flows lower into it; validation, derivation, and reporting passes operate over it; and each Renderer or export target consumes a form derived from it. The compiler should be able to inspect, normalize, and transform the IR without needing to reinterpret author-facing syntax at every stage.

The IR also creates a clean boundary with the Knowledge Compiler. The knowledge side of the platform may produce ontology updates, rule packs, or Standards Mapping artifacts, but those outputs should influence project compilation through explicit contracts rather than by bypassing the IR. In this architecture, Engineering IR remains the canonical representation of engineering instances, while knowledge artifacts govern how those instances are interpreted.

In practical terms, that means the pipeline should evolve toward multiple explicit intermediate forms rather than one overloaded representation:

Engineering Language
        ->
Engineering IR
        ->
Layout IR
        ->
Geometry IR
        ->
Renderer / Target

This model allows each stage to own one responsibility. Engineering IR captures semantic truth. Layout IR captures view intent. Geometry IR captures exact renderable structure. Targets such as SVG, QElectroTech, EPLAN, or other downstream systems should consume derived forms rather than becoming the place where semantics, layout, and geometry are permanently entangled.

For the same reason, Engineering DSL should describe engineering meaning, not page coordinates or ad hoc drawing mechanics. Layout concerns may eventually have their own author-facing language or declarative configuration surface, but that should remain downstream of semantic engineering intent rather than mixed into it.