Raptor/.agents/invariants/SPATIAL_TARGET_GENERALITY_INVARIANT.md

Spatial Target Generality Invariant

Scope

This invariant applies to:

• the Spatial dialect and its verifiers;
• ONNX-to-Spatial planning and lowering;
• graph transforms and scheduling over Spatial IR;
• target information consumed while optimizing Spatial IR;
• lowerings from Spatial to target-specific dialects.

Invariant

Spatial represents logical compute, dataflow, layout choices, parallel work, and target-independent resource requirements. It must remain usable by different targets, including PIM and future targets such as PULPIM.

Raptor may ingest target information and use it to choose Spatial layouts, partitions, placements, or schedules. That information must cross an explicit target interface and be expressed in target-neutral terms at the Spatial layer. The Spatial dialect and scheduler must not parse a simulator-specific configuration, depend on a target dialect, or encode one target's instruction latencies, memory hierarchy, communication protocol, or resource policy.

Target adapters own translating a target configuration into the neutral information consumed by Spatial. Target-specific dialects and their lowerings own instruction semantics, physical memory details, communication mechanisms, and final legality.

Ownership boundary

• Spatial IR owns logical and physical planning concepts shared across targets.
• A target adapter owns configuration parsing and cost-model construction.
• The scheduler consumes an injected cost/resource model; it does not infer a target from global PIM options or hardcoded constants.
• Spatial-to-target lowering makes the selected representation explicit.
• Target dialect verifiers reject target-specific illegal states.

Target-neutral information may include processor topology, operation and transfer cost queries, available parallel capacity, and opaque resource requirements. Names and APIs at this boundary must describe those concepts, not a particular simulator or target implementation.

Forbidden coupling

Do not:

• include PIM or PULPIM dialect headers in the Spatial dialect or scheduler;
• read PIM compiler globals directly from generic scheduling algorithms;
• parse pimsim-nn, PIMCOMP, or another simulator's schema in Spatial code;
• hardcode Arch-A timing, mesh, crossbar, memory, or vector constants in Spatial cost calculations;
• add target-named Spatial operations when an existing logical/layout concept expresses the invariant;
• repair target-specific legality in generic Spatial cleanup passes.

Required proof

Changes that use target information in Spatial must show:

• the target boundary or injected interface used;
• that Spatial IR remains valid without target-specific attributes;
• that an unknown or unsupported target fails clearly rather than silently using PIM defaults;
• unit coverage with at least two distinct target profiles when scheduling or cost decisions change;
• target-specific validation after lowering for every implemented target affected by the change.

If only one target implementation exists, keep the interface narrow and test it with two profiles. Do not add speculative target operations or a framework for unimplemented targets.