[Architecture] Refactor `app/api/forge-agent/route.ts` (1,072 lines) into Pipeline Middleware & Job Queue

[Darkvader-ship-it]

Estimated Effort: 4 weeks / 5 days

Impacted Subsystems / Files:

• app/api/forge-agent/route.ts
• lib/forge/payment-verifier.ts
• lib/forge/ai-pipeline.ts
• lib/forge/ipfs-publisher.ts

Context & Problem Statement:
app/api/forge-agent/route.ts is a 1,072-line monolithic handler managing HTTP 402 challenges, Soroban XDR verification, Gemini lore generation, Nano Banana API orchestration, Pollinations fallbacks, Pinata IPFS uploads, and on-chain mint calls in a single synchronous execution path.

Technical Requirements & Scope:

1. Decompose route handler into isolated pipeline steps (verifyPaymentStep, generateLoreStep, generateImageStep, publishIpfsStep, mintNftStep).
2. Implement async job status tracking with UUID correlation IDs.
3. Refactor fallback logic so Nano Banana timeouts cleanly cascade to Pollinations without failing the response.
4. Extract AI lore prompt construction into lib/forge/prompt-builder.ts.

Multi-File Change Surface:
Refactors app/api/forge-agent/route.ts completely and creates modular sub-libraries in lib/forge/.

Acceptance Criteria:

• Route file reduced to under 150 lines of execution orchestration.
• Zero synchronous blockages during external AI provider outages.
• 100% test coverage over payment verification pipeline stages.

Suggested Approach / Investigation Steps:

1. Map state payload transitions across current 1,072-line route file.
2. Create isolated module pipeline files in lib/forge/.
3. Implement integration test suite mocking external API failures.

---