PRD: Tuple-domain feasible set semantics (V1)

[pesap]

PRD: Tuple-Domain Feasible Set Semantics (V1)

Problem Statement

Today, tuple-like investment decisions in nodal allocation are effectively modeled with Cartesian-style domains plus filter guards, which is ambiguous and error-prone for users. We need a first-class feasible tuple domain so users can model only valid combinations, avoid boolean preprocessing artifacts, and receive deterministic compile-time diagnostics for data/model issues.

Solution

Introduce V1 tuple-domain feasible set semantics where feasible tuples are an explicit, authoritative domain for variable instantiation and constraint instantiation.

Core behavior:

• Variables indexed as x[a,i,g,b] represent membership in feasible tuples, not Cartesian expansion.
• Feasible tuples are sourced from both:
  • Data-backed rows
  • Rule-generated tuples
• When both sources are present, merge semantics are fixed to intersection (non-configurable in V1).
• Projection is explicit in V1 using named subset declarations with existing KDL form:
  • set ... { in ...; where { ... } }
• No new project DSL keyword is introduced.

User Stories

1. As a model author, I can define feasible combinations (a,i,g,b) explicitly so optimization variables are created only for valid tuples.
2. As a model author, I can combine row-based feasibility and rule-based feasibility and rely on deterministic intersection semantics.
3. As a model author, I can declare explicit subsets for reduced-scope constraints (e.g., area-tech targets) without hidden auto-projection.
4. As a model author, I receive actionable compile-time diagnostics for order mismatches, duplicates, and empty relevant subsets.
5. As an operator, I can trust stable, scoped identifiers in diagnostics/logs/artifacts for reproducible debugging.

Implementation Decisions

• Tuple component schema must be explicitly declared in set definitions (no inference).
• Tuple component order is forced; index order mismatches are hard compile-time errors with expected vs received order.
• Duplicate feasible tuples are hard data errors (no silent deduplication).
• Empty constraint-relevant tuple subsets are hard compile-time errors (not lowered to algebraic 0 == target).
• Empty-subset diagnostics must report all offending keys.
• Duplicate diagnostics must include full provenance:
  • data source + row number
  • rule source identifier/details
• Constraint and rule blocks must have stable IDs:
  • user-provided ID/name preferred
  • inferred when omitted
• Inferred IDs must be deterministic/stable and user-visible in compiler errors, logs, and exported artifacts.
• Inferred ID format is scoped; include scenario scope when relevant.
• Multi-key diagnostics are deterministically sorted by canonical tuple order.
• Non-math block syntax remains valid KDL node/property syntax; algebraic logic stays in math blocks.

Testing Decisions

• Parser/semantic tests for:
  • Explicit tuple schema declaration requirements
  • Reuse of set ... in ... where ... subset form for tuple subsets
  • Source merge = intersection-only behavior
• Compile-time validation tests for:
  • Index order mismatch hard errors (with expected vs received order)
  • Duplicate tuple hard errors with full provenance
  • Empty relevant subset hard errors reporting all offending keys
• Determinism tests for:
  • Stable inferred IDs across repeated runs
  • Stable scoped inferred ID formatting (scenario included when relevant)
  • Stable ordering of multi-key diagnostics
• Regression tests to ensure tuple-domain instantiation remains structurally sparse and avoids Cartesian fallback behavior.

Out of Scope

• Auto-projection of tuple sets from higher-dimensional domains.
• Configurable merge modes (e.g., union) in V1.
• New DSL predicates/keywords for projection (e.g., project).
• Soft/slack fallback for empty feasible subsets.
• Any attempt to support ambiguous tuple key indexing forms.

Further Notes

• This PRD formalizes V1 contracts already captured in ADR 0002.
• Recommended follow-up workflow: split into implementation issues by parser/semantic/compiler/diagnostics/testing tracks.