⚡ Multi-Instance & Error Cleanup - Blade Generation System

⚡ Multi-Instance Processing Strategy

🆕 Added January 8, 2026 - When to Use Parallel Processing

The overhead of spawning PEPS instances + JSON/XML IPC + file-based communication is significant (5-15 seconds startup). Use this decision table to determine when multi-instance processing is worthwhile.

📊 Decision Matrix

Scenario	Single Instance	Multi-Instance	Verdict
Single part, <20 blades	30-60 sec	45-60 sec (overhead wipes out gains)	Single
Single part, 50+ blades	3-5 min	1.5-2 min (blades are independent)	Maybe
Batch: 10+ parts queued	10× sequential time	Near-parallel processing	YES
Massive model (1000+ faces)	15-30 min	Distribute face analysis	YES
Quick validation/preview	10 sec	20 sec (overhead dominates)	Single

✅ Sweet Spot for Multi-Instance

Batch jobs from web API/CRM - multiple parts queued, farm them out to waiting instances
Blade-parallel processing - if you have 40+ blades, each blade profile is independent work
Analysis phases - weld detection, reach study, raycast validation on separate instances

❌ NOT Worth It For

Interactive single-part workflow
Anything under ~2 minutes total
Operations that are inherently sequential (can't parallelize)

🔄 JSON vs XML Data Format

RECOMMENDED ARCHITECTURE External Input → [Converter Layer] → Internal XML → PEPS ↑ ↑ JSON or XML Existing parser works Web UI → JSON → API → Convert to XML → PEPS B2B Partner A → JSON → API → Convert to XML → PEPS B2B Partner B → XML → API → Pass through → PEPS

Recommendation: Support both formats. JSON primary (90% of modern integrations), XML for legacy enterprise. Keep existing PEPS XML parser, add thin JSON→XML converter at API boundary (~50 lines of code).

📦 Existing Infrastructure

@@rstart.ovm - Entry point, detects -x (XML) and -w (waiting mode) flags

fxRunBackgroundInstance.ovm - Orchestrator, spawns multiple PEPS instances

fxExecuteBackgroundTasks.ovm - Worker, loads XML and executes fixture generation

fxLogInstance.ovm - XML-based semaphore system for status/heartbeat

🧹 Error Cleanup System (PLANNED)

🆕 Added January 8, 2026 - Next Week Priority

Comprehensive cleanup mechanism for macro errors. When a macro fails mid-execution, leftover state (globals, VDM data, temporary bodies, layers) can cause subsequent runs to fail or behave unexpectedly.

🔄 Cleanup Scope

Global Variables - Reset fixture globals to safe defaults (i_FX_*, w_FX_*)
VDM Slots - Clear/release allocated VDM sets (progress state, blade data, etc.)
Temporary Bodies - Delete orphaned solids from interrupted operations
Scratch Layers - Clean up temporary layers (@@NucleoProgress, etc.)
Position Marks - Restore SLD PMK state if interrupted mid-checkpoint
Window State - Restore graphics window on/off state

📋 Implementation Approach

ERROR CLEANUP ARCHITECTURE ┌─────────────────────────────────────────────────────────┐ │ onerror handler (per macro) │ │ ↓ │ │ call fxErrorCleanup $_MACRO_NAME │ │ ↓ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ fxErrorCleanup: │ │ │ │ • Reset i_FX_* globals to defaults │ │ │ │ • Clear VDM slots in known ranges │ │ │ │ • Delete bodies on temp layers │ │ │ │ • Restore window state │ │ │ │ • Log error context for debugging │ │ │ └─────────────────────────────────────────────────┘ │ │ ↓ │ │ Resume or exit gracefully │ └─────────────────────────────────────────────────────────┘

○ Create fxErrorCleanup.ovm master cleanup macro
○ Document all VDM slot allocations (create VDM_SLOTS.md)
○ Add onerror handlers to critical macros
○ Create fxResetGlobals.ovm for global variable reset
○ Test cleanup with intentional mid-macro failures
○ Add cleanup call to fxProgressUpdate on error paths

📦 Deliverables

fxErrorCleanup.ovm - Master cleanup utility

fxResetGlobals.ovm - Reset all fixture globals

VDM_SLOTS.md - Documentation of VDM slot allocations