chore(openspec): propose multipatch per-interface controls

docs/exec-plans/active/20260407-formdsl-iga-multipatch-interface-controls.md

@@ -0,0 +1,41 @@
+# Form DSL IGA Multipatch Interface Controls
+
+## Objective
+
+Add deterministic per-interface coupling controls for IGA multipatch assembly
+while preserving global fallback semantics.
+
+## Scope
+
+- Add optional per-interface penalty field in multipatch interface descriptors.
+- Validate interface penalties deterministically during parsing/IR checks.
+- Apply per-interface override precedence over global `multipatch_penalty`.
+- Expose effective interface penalty values in IGA payload metadata.
+- Add regression tests and docs updates.
+
+## Non-Goals
+
+- DG-SEM multipatch execution.
+- New coupling families beyond current penalty-style model.
+- Adaptive penalty tuning heuristics.
+
+## Acceptance Criteria
+
+- Valid per-interface penalties parse and propagate through IR.
+- Per-interface penalties override global penalty for targeted interfaces only.
+- Invalid penalty values fail deterministically.
+- IGA payload metadata reports effective interface penalties.
+- Regression tests and docs cover new behavior.
+
+## Implementation Checklist
+
+- [x] Add OpenSpec proposal/design/spec/tasks artifacts.
+- [ ] Implement descriptor and validation support for optional interface
+  penalties.
+- [ ] Implement IGA precedence and metadata exposure for effective penalties.
+- [ ] Add regression tests and docs updates.
+
+## Risks / Open Questions
+
+- Interface duplicates remain invalid regardless of penalties; no merge policy is
+  introduced in this phase.

docs/formdsl-nurbs-multipatch-evaluation.md

@@ -56,6 +56,10 @@ Implication:
 
 ## Tracking
 
+- Active OpenSpec change:
+  `openspec/changes/formdsl-iga-multipatch-interface-controls/`
+- Active execution plan:
+  `docs/exec-plans/active/20260407-formdsl-iga-multipatch-interface-controls.md`
 - Multipatch numerical coupling archive:
   `openspec/changes/archive/2026-04-07-formdsl-iga-multipatch-interface-coupling-numerics/`
 - Multipatch numerical completed plan:

docs/ufl-backend-support.md

@@ -176,3 +176,6 @@ These are tracked outcomes from the Phase 3 backlog tasks:
   `openspec/changes/archive/2026-04-07-formdsl-iga-multipatch-interface-coupling-numerics/`
   and
   `docs/exec-plans/completed/20260407-formdsl-iga-multipatch-interface-coupling-numerics.md`.
+  Per-interface coupling controls are tracked in active change
+  `openspec/changes/formdsl-iga-multipatch-interface-controls/` and active plan
+  `docs/exec-plans/active/20260407-formdsl-iga-multipatch-interface-controls.md`.

openspec/changes/formdsl-iga-multipatch-interface-controls/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-07

openspec/changes/formdsl-iga-multipatch-interface-controls/design.md

@@ -0,0 +1,50 @@
+## Context
+
+`multipatch_penalty` currently configures one scalar value for all IGA
+multipatch interfaces. Recent multipatch stress fixtures showed a practical need
+for heterogeneous interface weights while keeping deterministic behavior.
+
+## Goals / Non-Goals
+
+**Goals**
+
+- Add optional per-interface penalty control in multipatch descriptors.
+- Preserve deterministic fallback to global `multipatch_penalty` when interface
+  penalty is omitted.
+- Keep parsing and assembly validation deterministic for malformed penalties.
+- Expose effective interface penalties in IGA payload metadata.
+
+**Non-Goals**
+
+- DG-SEM multipatch execution.
+- Interface-family expansion beyond current penalty-style coupling model.
+- Runtime adaptive penalty heuristics.
+
+## Decisions
+
+1. Add optional `penalty` field on each interface descriptor.
+   - Rationale: keeps controls colocated with interface topology/orientation.
+
+2. Keep metadata-level `multipatch_penalty` as fallback.
+   - Rationale: backward-compatible behavior for existing payloads.
+
+3. Validate penalties at parse and IR-validation stages.
+   - Rationale: fail early with deterministic diagnostics before assembly.
+
+4. Record effective coupling penalty in `interface_lowering` metadata.
+   - Rationale: improves observability and testability of control precedence.
+
+## Risks / Trade-offs
+
+- [Risk] Duplicate interfaces with differing penalties may still be ambiguous.
+  - Mitigation: keep canonical duplicate rejection independent of penalty.
+- [Risk] Very large penalties can worsen conditioning.
+  - Mitigation: enforce finite positive values and leave numerical tuning to the
+    caller.
+
+## Migration Plan
+
+1. Extend OpenSpec requirements for per-interface coupling controls.
+2. Implement IR/parser support and deterministic penalty validation.
+3. Apply per-interface penalty precedence in IGA coupling assembly.
+4. Add regression tests/docs and update execution tracking.

openspec/changes/formdsl-iga-multipatch-interface-controls/proposal.md

@@ -0,0 +1,41 @@
+## Why
+
+IGA multipatch coupling now supports deterministic metadata and numerical
+interface contributions, but coupling strength is controlled only by one global
+metadata value (`multipatch_penalty`). This makes heterogeneous interface
+stabilization awkward because users cannot tune individual interfaces without
+changing all interface penalties.
+
+We need deterministic per-interface coupling controls so interface-specific
+penalties can be expressed directly in multipatch descriptors while preserving
+current global-default behavior.
+
+## What Changes
+
+- Extend multipatch interface descriptors with optional per-interface penalty
+  configuration.
+- Keep `multipatch_penalty` metadata as the global fallback when interface
+  penalty is omitted.
+- Validate per-interface penalties deterministically (finite, positive).
+- Surface effective interface penalties in IGA lowering payload metadata.
+- Add regression coverage for override precedence and malformed controls.
+
+## Capabilities
+
+### Modified Capabilities
+
+- `ufl-iga-form-dsl`: multipatch coupling control expands from global penalty
+  only to per-interface override controls with deterministic fallback semantics.
+
+### Unchanged Capabilities
+
+- `ufl-dgsem-form-dsl`: remains multipatch execution unsupported.
+
+## Impact
+
+- Affected code:
+  - `src/cutkit/formdsl/ir.py`
+  - `src/cutkit/formdsl/adapter.py`
+  - `src/cutkit/formdsl/iga_backend.py`
+  - `tests/formdsl/test_formdsl_assembly.py`
+  - docs updates under `docs/`

openspec/changes/formdsl-iga-multipatch-interface-controls/specs/form-dsl-backend-assembly/spec.md

@@ -0,0 +1,30 @@
+## ADDED Requirements
+
+### Requirement: Multipatch interface descriptors accept optional penalties
+The system SHALL accept optional finite positive per-interface penalty values in
+multipatch interface descriptors.
+
+#### Scenario: Parse interface descriptor with penalty
+- **WHEN** a multipatch interface descriptor includes a valid numeric positive
+  `penalty`
+- **THEN** parsing succeeds and IR retains the per-interface penalty value
+
+### Requirement: IGA multipatch coupling applies deterministic penalty precedence
+The system SHALL use per-interface `penalty` when present and otherwise fall
+back to global `multipatch_penalty` metadata.
+
+#### Scenario: Interface penalty overrides global penalty
+- **WHEN** a form provides both global `multipatch_penalty` metadata and a
+  specific interface `penalty`
+- **THEN** that interface uses its own penalty value during coupling assembly
+  and payload metadata reports the effective value
+
+### Requirement: Invalid interface penalties fail deterministically
+The system MUST reject malformed per-interface penalties with deterministic
+validation errors.
+
+#### Scenario: Non-finite or non-positive interface penalty
+- **WHEN** a multipatch interface descriptor specifies `penalty` that is
+  non-numeric, non-finite, or non-positive
+- **THEN** parsing or IR validation fails with deterministic error metadata
+  naming the invalid penalty field

openspec/changes/formdsl-iga-multipatch-interface-controls/tasks.md

@@ -0,0 +1,21 @@
+## 1. OpenSpec Artifacts
+
+- [x] 1.1 Add proposal/design/spec/tasks artifacts for per-interface multipatch
+  controls.
+
+## 2. Descriptor + Validation
+
+- [ ] 2.1 Add optional per-interface penalty field to multipatch interface
+  descriptors in IR/parser.
+- [ ] 2.2 Add deterministic validation for malformed per-interface penalties.
+
+## 3. IGA Coupling Integration
+
+- [ ] 3.1 Apply per-interface penalty override precedence in IGA interface
+  coupling assembly.
+- [ ] 3.2 Expose effective interface penalty values in lowering metadata.
+
+## 4. Validation + Docs
+
+- [ ] 4.1 Add regression tests for precedence behavior and malformed values.
+- [ ] 4.2 Update docs and execution-plan progress.