@specverse/engines 6.33.0 → 6.34.0

package/dist/libs/instance-factories/communication/rabbitmq-events.yaml

@@ -40,6 +40,17 @@ dependencies:
     - name: "typescript"
       version: "^5.2.0"
 
+# V2 factory metadata — Component Dependencies V2 proposal Section 4
+v2metadata:
+  topology: messaging                     # AMQP broker pub/sub; deploys as communications: instance
+  protocol: amqp                          # AMQP 0-9-1 (RabbitMQ)
+  authentication: { kind: bearer, mechanism: PLAIN }   # RabbitMQ credential pair (user/password)
+  supportedTopologies: [messaging]
+  serverTemplate: templates/rabbitmq/connection-generator.ts   # broker connection setup
+  clientTemplate: templates/rabbitmq/publisher-generator.ts    # publisher client for producers
+  emitsDeploymentInstance: true           # generates a communications: instance entry
+  deploymentCategory: communications      # lands in communications: category
+
 codeTemplates:
   publisher:
     engine: typescript

package/dist/libs/instance-factories/controllers/fastify.yaml

@@ -52,6 +52,17 @@ dependencies:
     - name: "tsx"
       version: "^4.0.0"
 
+# V2 factory metadata — Component Dependencies V2 proposal Section 4
+v2metadata:
+  topology: service                       # generates a Fastify HTTP server; deploys as services: instance
+  protocol: rest                          # HTTP/REST transport
+  authentication: { kind: bearer }        # typical JWT bearer auth; overridable per deployment
+  supportedTopologies: [service]
+  serverTemplate: templates/fastify/server-generator.ts   # server bind code (main.ts / server.ts)
+  clientTemplate: null                    # clients generated from TypeScript SDK factory (separate concern)
+  emitsDeploymentInstance: true           # generates a services: instance entry in deployment
+  deploymentCategory: services            # lands in services: category
+
 codeTemplates:
   routes:
     engine: typescript

package/dist/libs/instance-factories/managed/stripe-rest-sdk.yaml

@@ -0,0 +1,78 @@
+name: StripeRestSDK
+version: "1.0.0"
+category: infrastructure
+description: "Stripe payments SDK adapter — wraps the Stripe Node.js SDK with a typed SpecVerse client for managed payment processing"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [stripe, payments, managed, rest, sdk, infrastructure]
+
+compatibility:
+  specverse: ">=6.33.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "managed.payments"
+    - "managed.payments.stripe"
+  requires: []                            # external SaaS — no transitive SpecVerse deps
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  framework: "stripe-sdk"
+  version: "^14.0.0"
+
+# V2 factory metadata — Component Dependencies V2 proposal Section 4
+# Forward-looking stub: Round 2 realize emitters will consume these fields.
+v2metadata:
+  topology: managed                       # external SaaS via SDK; deploys as infrastructure: instance
+  protocol: rest                          # Stripe API uses HTTPS/REST under the hood
+  sdk: "stripe"                           # npm package name: https://www.npmjs.com/package/stripe
+  authentication: { kind: api-key, envVar: STRIPE_SECRET_KEY }   # Stripe uses API keys
+  supportedTopologies: [managed]
+  clientTemplate: templates/stripe/stripe-client-generator.ts    # typed wrapper exposing Charge.create etc.
+  serverTemplate: null                    # external SaaS — no server bind code emitted
+  emitsDeploymentInstance: true           # generates an infrastructure: instance entry in deployment
+  deploymentCategory: infrastructure      # lands in infrastructure: category (external SaaS)
+
+dependencies:
+  runtime:
+    - name: "stripe"
+      version: "^14.0.0"
+
+  dev:
+    - name: "@types/node"
+      version: "^20.8.0"
+    - name: "typescript"
+      version: "^5.2.0"
+
+# Minimal stub: codeTemplates to be fleshed out in Round 2 (per-runtime emitters)
+codeTemplates:
+  client:
+    engine: typescript
+    generator: "libs/instance-factories/managed/templates/stripe/stripe-client-generator.ts"
+    outputPattern: "{backendDir}/src/clients/StripeClient.ts"
+
+configuration:
+  envVar: "STRIPE_SECRET_KEY"
+  apiVersion: "2024-06-20"
+  webhookSecret: null                     # optional: STRIPE_WEBHOOK_SECRET for signature verification
+
+requirements:
+  dependencies:
+    npm:
+      dependencies:
+        "stripe": "^14.0.0"
+  environment:
+    - name: "STRIPE_SECRET_KEY"
+      description: "Stripe secret API key"
+      example: "sk_live_..."
+      required: true
+      category: "Payments"
+    - name: "STRIPE_WEBHOOK_SECRET"
+      description: "Stripe webhook signing secret (required only if handling webhooks)"
+      example: "whsec_..."
+      required: false
+      category: "Payments"

package/dist/libs/instance-factories/managed/templates/stripe/stripe-client-generator.js

@@ -0,0 +1,8 @@
+async function generate(_context) {
+  throw new Error(
+    "StripeRestSDK client generator is a V2 Round 2 stub. The managed-runtime realize emitter is not yet implemented. See Component Dependencies V2 proposal Phase 3."
+  );
+}
+export {
+  generate
+};

package/dist/libs/instance-factories/orms/prisma.yaml

@@ -40,6 +40,17 @@ dependencies:
     - name: "typescript"
       version: "^5.2.0"
 
+# V2 factory metadata — Component Dependencies V2 proposal Section 4
+v2metadata:
+  topology: library                       # in-process ORM client; no deployment instance emitted
+                                          # protocol: omitted — not applicable for library topology
+  authentication: { kind: none }          # auth is the DB connection string, not a protocol-level scheme
+  supportedTopologies: [library]
+  clientTemplate: null                    # client is the generated Prisma client itself
+  serverTemplate: null                    # no server component
+  emitsDeploymentInstance: false          # library-shaped; consumer manages DB config via storage: instance
+  deploymentCategory: storage             # informational: if a storage: instance existed, it would land here
+
 codeTemplates:
   schema:
     engine: typescript

package/dist/realize/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/realize/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,kBAAkB,CAAC;AAGjC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,uBAAuB,CAAC;AAItC,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAMlE,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AA0DnF,cAAM,sBAAuB,YAAW,aAAa;IACnD,IAAI,SAAa;IACjB,OAAO,SAAW;IAClB,YAAY,WAA+E;IAE3F,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,WAAW,CAAS;IAEtB,UAAU,CAAC,MAAM,CAAC,EAAE;QACxB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,IAAI,CAAC;IAwDjB,OAAO,IAAI,UAAU;IAIrB,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG;IAK1B,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,eAAe,CAAC;IAKvF;;;OAGG;IACG,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAw0B9F;;;OAGG;YACW,UAAU;IA8DxB,OAAO,CAAC,oBAAoB;CAuB7B;AAED,eAAO,MAAM,MAAM,wBAA+B,CAAC;AACnD,eAAe,MAAM,CAAC;AACtB,OAAO,EAAE,sBAAsB,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/realize/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,kBAAkB,CAAC;AAGjC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,uBAAuB,CAAC;AAItC,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAMlE,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AA2DnF,cAAM,sBAAuB,YAAW,aAAa;IACnD,IAAI,SAAa;IACjB,OAAO,SAAW;IAClB,YAAY,WAA+E;IAE3F,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,WAAW,CAAS;IAEtB,UAAU,CAAC,MAAM,CAAC,EAAE;QACxB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,IAAI,CAAC;IAwDjB,OAAO,IAAI,UAAU;IAIrB,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG;IAK1B,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,eAAe,CAAC;IAKvF;;;OAGG;IACG,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAomC9F;;;OAGG;YACW,UAAU;IA8DxB,OAAO,CAAC,oBAAoB;CAuB7B;AAED,eAAO,MAAM,MAAM,wBAA+B,CAAC;AACnD,eAAe,MAAM,CAAC;AACtB,OAAO,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/realize/index.js

@@ -17,6 +17,7 @@ export { createCodeGenerator } from './engines/code-generator.js';
 import { writeFileSync, existsSync, mkdirSync, readdirSync, statSync, copyFileSync } from 'fs';
 import { dirname, join, basename } from 'path';
 import { fileURLToPath } from 'url';
+import yaml from 'js-yaml';
 import { createDefaultLibrary } from './library/library.js';
 import { createResolver } from './library/resolver.js';
 import { createCodeGenerator } from './engines/code-generator.js';
@@ -354,20 +355,39 @@ class SpecVerseRealizeEngine {
                     }
                 }
                 // ─── Per-action path (default and only path since Phase 3b) ───
-                const { runPerActionEmission } = await import('./per-action-runner.js');
+                const { runPerActionEmission, buildAvailableClientsByOwner } = await import('./per-action-runner.js');
                 const { createRealizeActionLlmEmit } = await import('./per-action-llm-emit.js');
                 // Prefer the ORM-specific shared matcher when available; fall back to
                 // the prisma matchAgainstConventions with the loaded convention array.
-                const sharedMatcher = matcher ?? (conventions
-                    ? (await import(join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'libs', 'instance-factories', 'services', 'templates', '_shared', 'step-matching.ts').replace(/\.ts$/, '.js'))).matchAgainstConventions
-                    : undefined);
+                // Use resolveGenPath (defined above) which handles published-package
+                // structure correctly: it checks dist/libs/ first (compiled .js for
+                // installed packages) before falling back to libs/ (source .ts for
+                // dev). The previous inline `.replace(/\.ts$/, '.js')` only checked
+                // libs/.../step-matching.js which doesn't exist in either location —
+                // published packages have it at dist/libs/.../step-matching.js.
+                let sharedMatcher = matcher;
+                if (!sharedMatcher && conventions) {
+                    const sharedMatcherTsPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'libs', 'instance-factories', 'services', 'templates', '_shared', 'step-matching.ts');
+                    const sharedMatcherSrc = resolveGenPath(sharedMatcherTsPath);
+                    if (sharedMatcherSrc) {
+                        const sharedMod = await import(sharedMatcherSrc);
+                        sharedMatcher = sharedMod.matchAgainstConventions;
+                    }
+                }
                 // LLM emit hook — only fires when an AI provider is configured.
                 const llmEmit = createRealizeActionLlmEmit({});
+                // Round 3 follow-up: thread V2 imports → LLM prompt's
+                // `availableClients` slot. Built from spec.components[].import,
+                // keyed by owner so the runner can drop the per-component string
+                // into RealizeContext as it walks each owner. Empty map when no
+                // component declares V2 imports — runner is a no-op then.
+                const availableClientsByOwner = buildAvailableClientsByOwner(spec);
                 const result = await runPerActionEmission({
                     spec, outputDir,
                     matcher: sharedMatcher,
                     conventions,
                     llmEmit,
+                    availableClientsByOwner,
                     silent: false,
                 });
                 if (result.totals.actionCount > 0) {
@@ -378,6 +398,243 @@ class SpecVerseRealizeEngine {
                 errors.push(`AI Behaviors: ${e.message}`);
             }
         }
+        // 2.6 V2 imports — per-component runtime client emission
+        //
+        // For each component's `import:` block, resolve the `from:` reference via
+        // the V2 dependency resolver (4-step chain: local → npm → registry library
+        // → registry factory) and dispatch to the right per-runtime emitter
+        // (library / service / managed / executable / messaging) keyed by factory
+        // v2metadata.topology. This is the wire-up that makes V2 P3's framework
+        // actually drive code emission end-to-end.
+        //
+        // Factory binding (R3 follow-up): for each import the provider's deployment
+        // instance is looked up in the spec by `instance.component === resolved.resolvedName`
+        // across all 8 instance categories. The first `advertises:` capability is
+        // then resolved via manifest.capabilityMappings to an instanceFactory name,
+        // which is fetched from the InstanceFactoryLibrary. If the factory has
+        // v2metadata, it drives dispatch; otherwise we fall back to a synthetic
+        // library-topology factory (in-process default) so consumers without
+        // explicit topology bindings still get a typed wrapper.
+        //
+        // Output: clients/<provider>.ts (and servers/<provider>-server.ts for
+        // service topology when serverTemplate is set) under <outputDir>/backend/src/<ConsumerComponent>/.
+        //
+        // Resolver registry steps (3+4) are stubbed in Round 1; offline mode and
+        // local + npm sources work fully.
+        //
+        // Deliberately no-op when a component has no `import:` entries — V2 is
+        // additive; existing specs are unaffected.
+        // Helper: walk all deployments in the spec, find the first instance whose
+        // `component:` matches the resolved provider name. Searches across the 8
+        // instance categories (controllers / services / views / communications /
+        // storage / security / infrastructure / monitoring).
+        const findDeploymentInstanceForProvider = (providerName) => {
+            const deployments = Array.isArray(spec.deployments)
+                ? spec.deployments
+                : Object.values(spec.deployments ?? {});
+            for (const dep of deployments) {
+                const instances = dep.instances ?? {};
+                for (const categoryKey of Object.keys(instances)) {
+                    const category = instances[categoryKey];
+                    if (!category || typeof category !== 'object')
+                        continue;
+                    for (const instanceKey of Object.keys(category)) {
+                        const inst = category[instanceKey];
+                        if (inst && typeof inst === 'object' && inst.component === providerName) {
+                            return inst;
+                        }
+                    }
+                }
+            }
+            return null;
+        };
+        // Helper: pick a factory for an import. Priority chain:
+        //   1. Resolved provider's deployment instance → first `advertises:` capability
+        //      → manifest.capabilityMappings → library.get(instanceFactory).
+        //   2. Synthetic library-topology default (the safe in-process fallback).
+        const syntheticLibraryFactory = {
+            name: 'LibraryRuntimeDefault',
+            version: '1.0.0',
+            category: 'service',
+            capabilities: { provides: [], requires: [] },
+            technology: { runtime: 'node', framework: 'typescript', language: 'typescript' },
+            v2metadata: { topology: 'library', emitsDeploymentInstance: false },
+        };
+        // Helper: strip a trailing 'Client' suffix from an emitter-returned
+        // specifier so the v2Clients aggregator keys are clean (e.g. specifier
+        // 'profitCalculatorClient' → key 'profitCalculator').
+        const stripTrailingClient = (specifier) => specifier.endsWith('Client') ? specifier.slice(0, -'Client'.length) : specifier;
+        const pickFactoryForImport = (resolved) => {
+            const providerName = resolved.resolvedName ?? resolved.fromName;
+            if (!providerName)
+                return syntheticLibraryFactory;
+            const deployInstance = findDeploymentInstanceForProvider(providerName);
+            const advertises = deployInstance?.advertises;
+            const firstCap = Array.isArray(advertises) ? advertises[0] : undefined;
+            if (typeof firstCap !== 'string' || firstCap.length === 0) {
+                return syntheticLibraryFactory;
+            }
+            const mappings = this.manifest?.capabilityMappings ?? this.manifest?.manifests?.[0]?.capabilityMappings ?? [];
+            const mapping = (Array.isArray(mappings) ? mappings : []).find((m) => m?.capability === firstCap);
+            const factoryName = mapping?.instanceFactory;
+            if (typeof factoryName !== 'string' || factoryName.length === 0) {
+                return syntheticLibraryFactory;
+            }
+            // Look up the factory in the library. If it has v2metadata, use it;
+            // otherwise fall back to the synthetic default. Pre-V2 factories without
+            // v2metadata can't drive topology-specific emitters; the loader's
+            // applyV2MetadataDefaults fills v2metadata for canonical factories, so
+            // this fallback is the safety net for malformed manifests.
+            const factory = this.library?.get?.(factoryName);
+            if (factory && factory.v2metadata) {
+                return factory;
+            }
+            return syntheticLibraryFactory;
+        };
+        try {
+            const { createDependencyResolver } = await import('./resolver/index.js');
+            const { dispatchRuntimeEmitter, buildDefaultEmitters } = await import('./runtime-emitters/dispatcher.js');
+            const dependencyResolver = createDependencyResolver();
+            const runtimeEmitters = await buildDefaultEmitters();
+            let importsEmitted = 0;
+            // V2 P3 R3 follow-up: collect structured deployment-instance
+            // suggestions across every consumer component so the run produces
+            // a single aggregated v2-deployment-suggestions.yaml at the
+            // top-level outputDir. Library-topology emissions don't contribute.
+            const allDeploymentSuggestions = [];
+            const componentsList = Array.isArray(spec.components)
+                ? spec.components
+                : Object.values(spec.components ?? {});
+            for (const consumerComp of componentsList) {
+                const imports = consumerComp.imports ?? [];
+                if (!Array.isArray(imports) || imports.length === 0)
+                    continue;
+                // Track per-component imports for the aggregator file (clients/index.ts).
+                // Each entry: { from: file path (without .js), specifier: client const name }
+                const aggregatorEntries = [];
+                const componentName = consumerComp.name ?? 'unknown';
+                const componentOutputDir = join(outputDir, 'backend', 'src', componentName);
+                for (const importEntry of imports) {
+                    try {
+                        const fromName = importEntry.from;
+                        if (typeof fromName !== 'string' || fromName.length === 0)
+                            continue;
+                        const resolved = await dependencyResolver.resolve(fromName, importEntry.version, { spec, offline: !!process.env.SPECVERSE_OFFLINE });
+                        if (!resolved)
+                            continue;
+                        const factory = pickFactoryForImport(resolved);
+                        const emitter = dispatchRuntimeEmitter(factory, runtimeEmitters);
+                        const result = await emitter.emit({
+                            consumerComponent: consumerComp,
+                            importEntry: {
+                                from: fromName,
+                                version: importEntry.version,
+                                select: importEntry.select ?? [],
+                            },
+                            resolved,
+                            factory,
+                            outputDir: componentOutputDir,
+                            spec: spec,
+                        });
+                        for (const file of result.files) {
+                            const filePath = join(componentOutputDir, file.path);
+                            writeOutput({ filePath, code: file.content });
+                            importsEmitted += 1;
+                        }
+                        // Collect the consumer-import declarations the emitter returned so
+                        // we can write the per-component clients/index.ts aggregator below.
+                        for (const consumerImport of (result.imports ?? [])) {
+                            aggregatorEntries.push(consumerImport);
+                        }
+                        // Collect structured deployment-instance suggestion (V2 P3 R3
+                        // follow-up). Library emitters omit this field; only service /
+                        // managed / executable / messaging contribute.
+                        if (result.deploymentSuggestion) {
+                            allDeploymentSuggestions.push(result.deploymentSuggestion);
+                        }
+                    }
+                    catch (importErr) {
+                        const compName = consumerComp.name ?? '<unknown>';
+                        const fromName = importEntry.from ?? '<unknown>';
+                        errors.push(`V2 import ${compName}.${fromName}: ${importErr.message}`);
+                    }
+                }
+                // Per-component aggregator: clients/index.ts re-exports every V2
+                // client emitted for this consumer + a combined `v2Clients` constant
+                // so consumers can `import { v2Clients } from './clients'` and spread
+                // it into their deps object. This is the cleanest seam between the
+                // V2 emission phase and the per-action emitter (L3 P3) without
+                // requiring controller-template surgery — the consumer's existing
+                // code just imports + spreads.
+                if (aggregatorEntries.length > 0) {
+                    const lines = [];
+                    lines.push('// FACTORY-EMITTED — DO NOT EDIT (R8)');
+                    lines.push('// V2 P3 imports aggregator. Re-exports every emitted client + a combined map.');
+                    lines.push('// Consumer usage:');
+                    lines.push('//   import { v2Clients } from \'./clients\';');
+                    lines.push('//   const deps = { ...existing, ...v2Clients };');
+                    lines.push('');
+                    // Static imports.
+                    for (const entry of aggregatorEntries) {
+                        const localPath = entry.from.replace(/^\.\/clients\//, './');
+                        lines.push(`import { ${entry.specifier} } from '${localPath}.js';`);
+                    }
+                    lines.push('');
+                    // Re-exports.
+                    for (const entry of aggregatorEntries) {
+                        lines.push(`export { ${entry.specifier} };`);
+                    }
+                    lines.push('');
+                    // Aggregated map keyed by client name with trailing 'Client' stripped
+                    // (v2Clients.profitCalculator rather than v2Clients.profitCalculatorClient).
+                    lines.push('export const v2Clients = {');
+                    for (const entry of aggregatorEntries) {
+                        lines.push(`  ${stripTrailingClient(entry.specifier)}: ${entry.specifier},`);
+                    }
+                    lines.push('} as const;');
+                    lines.push('');
+                    lines.push('export type V2Clients = typeof v2Clients;');
+                    lines.push('');
+                    const aggregatorPath = join(componentOutputDir, 'clients', 'index.ts');
+                    writeOutput({ filePath: aggregatorPath, code: lines.join('\n') });
+                }
+            }
+            if (importsEmitted > 0) {
+                console.log(`   ✅ V2 imports: ${importsEmitted} client file(s) emitted`);
+            }
+            // V2 P3 R3 follow-up: write v2-deployment-suggestions.yaml when any
+            // emitter returned a structured suggestion. Auto-merge into the
+            // user's deployments block isn't safe (env-specific values, secrets,
+            // scaling parameters), so this is review-then-paste material.
+            if (allDeploymentSuggestions.length > 0) {
+                const yamlBody = yaml.dump({ suggestions: allDeploymentSuggestions }, { indent: 2, lineWidth: 100, noRefs: true, sortKeys: false });
+                const header = [
+                    '# FACTORY-EMITTED — DO NOT EDIT (R8)',
+                    '# V2 P3 R3 follow-up: deployment-instance suggestions extracted from runtime emitters.',
+                    '#',
+                    '# Each entry corresponds to one V2 import that produced a non-library client.',
+                    '# Merge these into your deployments.<env>.instances.<category> block manually:',
+                    '#',
+                    '#   deployments:',
+                    '#     production:',
+                    '#       instances:',
+                    '#         <category>:',
+                    '#           <key>:',
+                    '#             <config keys from this file>',
+                    '#',
+                    '# Auto-merge is intentionally NOT performed: deployment shape is user-controlled',
+                    '# (env-specific values, secrets, scaling parameters). Review each suggestion before',
+                    '# pasting; placeholder markers like <url> indicate values you must supply.',
+                    '',
+                ].join('\n');
+                const suggestionsPath = join(outputDir, 'v2-deployment-suggestions.yaml');
+                writeOutput({ filePath: suggestionsPath, code: header + yamlBody });
+                console.log(`   ✅ V2 deployment suggestions: ${allDeploymentSuggestions.length} entry(ies) → v2-deployment-suggestions.yaml`);
+            }
+        }
+        catch (e) {
+            errors.push(`V2 imports phase: ${e.message}`);
+        }
         // 3. Services
         const servicesList = Array.isArray(spec.services) ? spec.services : Object.values(spec.services || {});
         if (ctrlResolved?.instanceFactory?.codeTemplates?.services) {