@specverse/engines 6.33.1 → 6.35.0

package/dist/realize/runtime-emitters/dispatcher.js

@@ -0,0 +1,76 @@
+/**
+ * Per-runtime emitter dispatcher — V2 Phase 3, Round 1.
+ *
+ * Proposal: 2026-05-08-COMPONENT-DEPENDENCIES-V2.md, "Realize bridge" section.
+ *
+ * The dispatcher is a small registry + lookup framework. The real work lives in
+ * each topology-specific emitter implementation (library.ts, and future
+ * service.ts / managed.ts / executable.ts / messaging.ts files).
+ *
+ * Round 1 ships: dispatcher framework + library topology emitter (this file +
+ * library.ts). The two cross-branch types — `ResolvedComponent` (Agent A) and
+ * `FactoryV2Metadata` / `InstanceFactory` (Agent B) — are imported from their
+ * canonical locations: Round 1d (this commit) reconciled the local stubs with
+ * the merged real types.
+ *
+ * Round 2 will add: service, managed, executable, messaging emitters + CLI wiring.
+ */
+// ─── Dispatcher ───────────────────────────────────────────────────────────────
+/**
+ * Look up the correct emitter for the factory's topology.
+ *
+ * The emitters map is injected by the caller, making the dispatcher
+ * extensible without engine changes: register new emitters by adding
+ * entries to the map.
+ *
+ * @param factory - The resolved factory metadata (drives the topology lookup).
+ * @param emitters - Registry of topology → RuntimeEmitter. Typically built
+ *   once per realize run by `buildDefaultEmitters()`.
+ * @returns The matching RuntimeEmitter.
+ * @throws Error if no emitter is registered for the factory's topology.
+ */
+export function dispatchRuntimeEmitter(factory, emitters) {
+    // V2 P3 R1d reconciliation: Agent B's loader populates factory.v2metadata
+    // (with topology defaulted from factory.category). Pre-V2 factories
+    // without v2metadata fall back to 'library' — the only emitter Round 1
+    // registers, so dispatch is deterministic.
+    const topology = factory.v2metadata?.topology ?? 'library';
+    const emitter = emitters.get(topology);
+    if (!emitter) {
+        const available = Array.from(emitters.keys()).sort().join(', ');
+        throw new Error(`No runtime emitter registered for topology '${topology}'. Available: ${available || '(none)'}`);
+    }
+    return emitter;
+}
+/**
+ * Build the default emitter registry for a realize run.
+ *
+ * Round 1 shipped library; Round 2 added service / managed / executable /
+ * messaging. All 5 are registered here so the realize-side dispatcher can
+ * pick whichever the factory's v2metadata.topology selects.
+ *
+ * The 'external' topology is intentionally NOT registered — V2's design
+ * defines it as a passthrough requiring manual wiring (no auto-emission).
+ * Specs that bind a factory with topology: 'external' will trip a clear
+ * "No runtime emitter registered" error, which is the desired behavior.
+ *
+ * Imports are deferred to avoid circular deps — each emitter file imports
+ * only from dispatcher.ts, not vice versa.
+ */
+export async function buildDefaultEmitters() {
+    const [{ LibraryRuntimeEmitter }, { ServiceRuntimeEmitter }, { ManagedRuntimeEmitter }, { ExecutableRuntimeEmitter }, { MessagingRuntimeEmitter },] = await Promise.all([
+        import('./library.js'),
+        import('./service.js'),
+        import('./managed.js'),
+        import('./executable.js'),
+        import('./messaging.js'),
+    ]);
+    const map = new Map();
+    map.set('library', new LibraryRuntimeEmitter());
+    map.set('service', new ServiceRuntimeEmitter());
+    map.set('managed', new ManagedRuntimeEmitter());
+    map.set('executable', new ExecutableRuntimeEmitter());
+    map.set('messaging', new MessagingRuntimeEmitter());
+    return map;
+}
+//# sourceMappingURL=dispatcher.js.map

package/dist/realize/runtime-emitters/dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../../src/realize/runtime-emitters/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAyIH,iFAAiF;AAEjF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAwB,EACxB,QAAqC;IAErC,0EAA0E;IAC1E,oEAAoE;IACpE,uEAAuE;IACvE,2CAA2C;IAC3C,MAAM,QAAQ,GAAoB,OAAO,CAAC,UAAU,EAAE,QAAQ,IAAI,SAAS,CAAC;IAC5E,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChE,MAAM,IAAI,KAAK,CACb,+CAA+C,QAAQ,iBAAiB,SAAS,IAAI,QAAQ,EAAE,CAChG,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB;IACxC,MAAM,CACJ,EAAE,qBAAqB,EAAE,EACzB,EAAE,qBAAqB,EAAE,EACzB,EAAE,qBAAqB,EAAE,EACzB,EAAE,wBAAwB,EAAE,EAC5B,EAAE,uBAAuB,EAAE,EAC5B,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACpB,MAAM,CAAC,cAAc,CAAC;QACtB,MAAM,CAAC,cAAc,CAAC;QACtB,MAAM,CAAC,cAAc,CAAC;QACtB,MAAM,CAAC,iBAAiB,CAAC;QACzB,MAAM,CAAC,gBAAgB,CAAC;KACzB,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,IAAI,GAAG,EAA0B,CAAC;IAC9C,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,qBAAqB,EAAE,CAAC,CAAC;IAChD,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,qBAAqB,EAAE,CAAC,CAAC;IAChD,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,qBAAqB,EAAE,CAAC,CAAC;IAChD,GAAG,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,wBAAwB,EAAE,CAAC,CAAC;IACtD,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,uBAAuB,EAAE,CAAC,CAAC;IACpD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/realize/runtime-emitters/executable.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Executable-runtime emitter — V2 Phase 3, Round 2.
+ *
+ * Handles `topology: 'executable'` factories: providers reached via
+ * `spawnSync` / `execSync` — local CLI binaries such as gitnexus, ffmpeg,
+ * or custom binaries.
+ *
+ * For each `import:` entry the consumer declares, this emitter produces:
+ *   clients/<kebab-provider>.ts   — spawnSync wrapper with typed interface
+ *
+ * The generated client module:
+ *   - Emits an `assertBinaryAvailable()` function called at module load
+ *     that runs `spawnSync('which', [binary])` (or `spawnSync(binary, ['--version'])`
+ *     as fallback) to fail loud at boot if the binary isn't on PATH.
+ *   - Exports a `<ProviderName>Client` TypeScript interface matching the
+ *     selected operations from `import.select`.
+ *   - Exports a `<providerName>Client` constant that implements the interface
+ *     by dispatching to `spawnSync`:
+ *       * Dotted op `Subcommand.action`: runs `spawnSync(binary, ['subcommand', 'action', ...args])`.
+ *       * Bare entity: runs `spawnSync(binary, [entity.toLowerCase(), ...args])`.
+ *     stdout is parsed as JSON; non-zero exit throws a clear Error.
+ *
+ * --- Binary name resolution ---
+ *
+ * The binary name is read from:
+ *   1. `factory.v2metadata.config?.binary` (explicit override)
+ *   2. `factory.name` lowercased (e.g. 'Gitnexus' → 'gitnexus')
+ *
+ * --- Select grammar ---
+ *
+ * Follows V2 D2 resolution (same as library.ts):
+ *   - Dotted: `Subcommand.action` → dispatches `spawnSync(binary, ['subcommand', 'action', ...])`.
+ *   - Bare:   `EntityName`        → dispatches `spawnSync(binary, [entityname, ...])`.
+ *
+ * --- No server file ---
+ *
+ * Subprocess providers don't have a server-bind file.
+ *
+ * --- Deployment instance hint ---
+ *
+ * Emitter notes include a hint to add the provider to
+ * `deployments.<env>.instances.infrastructure.<provider>` with
+ * `config: { binary: <name> }`.
+ */
+import type { RuntimeEmitter, RuntimeEmitterContext, RuntimeEmitterResult } from './dispatcher.js';
+/**
+ * Executable-runtime emitter implementation.
+ *
+ * One call to `emit()` processes a single `import:` entry and produces
+ * one client file under `clients/<provider-filename>.ts`.
+ * No server-bind file is emitted (subprocess providers have no server).
+ */
+export declare class ExecutableRuntimeEmitter implements RuntimeEmitter {
+    readonly topology: "executable";
+    emit(ctx: RuntimeEmitterContext): Promise<RuntimeEmitterResult>;
+}
+//# sourceMappingURL=executable.d.ts.map

package/dist/realize/runtime-emitters/executable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executable.d.ts","sourceRoot":"","sources":["../../../src/realize/runtime-emitters/executable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,iBAAiB,CAAC;AAuOzB;;;;;;GAMG;AACH,qBAAa,wBAAyB,YAAW,cAAc;IAC7D,QAAQ,CAAC,QAAQ,EAAG,YAAY,CAAU;IAEpC,IAAI,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAsFtE"}

package/dist/realize/runtime-emitters/executable.js

@@ -0,0 +1,316 @@
+/**
+ * Executable-runtime emitter — V2 Phase 3, Round 2.
+ *
+ * Handles `topology: 'executable'` factories: providers reached via
+ * `spawnSync` / `execSync` — local CLI binaries such as gitnexus, ffmpeg,
+ * or custom binaries.
+ *
+ * For each `import:` entry the consumer declares, this emitter produces:
+ *   clients/<kebab-provider>.ts   — spawnSync wrapper with typed interface
+ *
+ * The generated client module:
+ *   - Emits an `assertBinaryAvailable()` function called at module load
+ *     that runs `spawnSync('which', [binary])` (or `spawnSync(binary, ['--version'])`
+ *     as fallback) to fail loud at boot if the binary isn't on PATH.
+ *   - Exports a `<ProviderName>Client` TypeScript interface matching the
+ *     selected operations from `import.select`.
+ *   - Exports a `<providerName>Client` constant that implements the interface
+ *     by dispatching to `spawnSync`:
+ *       * Dotted op `Subcommand.action`: runs `spawnSync(binary, ['subcommand', 'action', ...args])`.
+ *       * Bare entity: runs `spawnSync(binary, [entity.toLowerCase(), ...args])`.
+ *     stdout is parsed as JSON; non-zero exit throws a clear Error.
+ *
+ * --- Binary name resolution ---
+ *
+ * The binary name is read from:
+ *   1. `factory.v2metadata.config?.binary` (explicit override)
+ *   2. `factory.name` lowercased (e.g. 'Gitnexus' → 'gitnexus')
+ *
+ * --- Select grammar ---
+ *
+ * Follows V2 D2 resolution (same as library.ts):
+ *   - Dotted: `Subcommand.action` → dispatches `spawnSync(binary, ['subcommand', 'action', ...])`.
+ *   - Bare:   `EntityName`        → dispatches `spawnSync(binary, [entityname, ...])`.
+ *
+ * --- No server file ---
+ *
+ * Subprocess providers don't have a server-bind file.
+ *
+ * --- Deployment instance hint ---
+ *
+ * Emitter notes include a hint to add the provider to
+ * `deployments.<env>.instances.infrastructure.<provider>` with
+ * `config: { binary: <name> }`.
+ */
+// ─── Naming helpers (mirrors library.ts) ─────────────────────────────────────
+/**
+ * Parse a select entry into head + optional tail.
+ * Dotted: `Subcommand.action` → { head: 'Subcommand', tail: 'action' }
+ * Bare:   `EntityName`        → { head: 'EntityName', tail: undefined }
+ */
+function parseSelectEntry(entry) {
+    const dotIndex = entry.indexOf('.');
+    if (dotIndex === -1) {
+        return { head: entry, tail: undefined };
+    }
+    return {
+        head: entry.slice(0, dotIndex),
+        tail: entry.slice(dotIndex + 1),
+    };
+}
+/**
+ * Normalise a `from:` name into an array of words for identifier generation.
+ * Same implementation as library.ts — handles camelCase, scoped packages, hyphens.
+ */
+function toWords(fromName) {
+    const normalised = fromName.replace(/^@/, '').replace(/\//g, '-');
+    return normalised
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .replace(/[^a-zA-Z0-9]+/g, ' ')
+        .trim()
+        .split(' ')
+        .filter(Boolean)
+        .map((w) => w.toLowerCase());
+}
+/**
+ * Convert a from-name to a lower-camelCase client constant name.
+ * 'Gitnexus' → 'gitnexus', 'GitNexus' → 'gitNexus', '@ffmpeg/core' → 'ffmpegCore'
+ */
+function toClientName(fromName) {
+    const words = toWords(fromName);
+    if (words.length === 0)
+        return 'unknownClient';
+    return (words[0] +
+        words
+            .slice(1)
+            .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+            .join(''));
+}
+/**
+ * Convert a from-name to a PascalCase interface name suffix.
+ * 'Gitnexus' → 'Gitnexus', 'GitNexus' → 'Gitnexus', '@ffmpeg/core' → 'FfmpegCore'
+ */
+function toInterfaceName(fromName) {
+    const words = toWords(fromName);
+    return words.map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+}
+/**
+ * Convert a from-name to a filesystem-safe kebab-case filename.
+ * 'Gitnexus' → 'gitnexus', 'GitNexus' → 'git-nexus', '@ffmpeg/core' → 'ffmpeg-core'
+ */
+function toFileName(fromName) {
+    return toWords(fromName).join('-');
+}
+// ─── Binary name resolution ───────────────────────────────────────────────────
+/**
+ * Resolve the binary name for spawnSync.
+ *
+ * Priority:
+ *   1. `factory.v2metadata.config?.binary` (explicit override)
+ *   2. `factory.name` lowercased (e.g. 'Gitnexus' → 'gitnexus',
+ *      'SubprocessCLIAdapter' → 'subprocesscliadapter' — callers should
+ *      prefer explicit `config.binary` for multi-word names)
+ */
+function resolveBinaryName(factory) {
+    const configBinary = factory.v2metadata
+        ?.config?.binary;
+    if (configBinary && typeof configBinary === 'string' && configBinary.length > 0) {
+        return configBinary;
+    }
+    return factory.name.toLowerCase();
+}
+// ─── Code-generation helpers ──────────────────────────────────────────────────
+/**
+ * Generate the `assertBinaryAvailable()` function that runs at module load.
+ *
+ * Uses `spawnSync('which', [binary])` as primary check (POSIX); on non-zero
+ * exit falls back to `spawnSync(binary, ['--version'])`. If both fail, throws
+ * a descriptive error pointing at the env-var escape hatch.
+ *
+ * The env-var name is SPECVERSE_<BINARY_UPPER>_PATH (e.g. SPECVERSE_PROFIT_CALC_PATH).
+ */
+function generateBinaryAvailabilityCheck(binary) {
+    const envVar = `SPECVERSE_${binary.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_PATH`;
+    const lines = [];
+    lines.push(`import { spawnSync } from 'child_process';`);
+    lines.push('');
+    lines.push(`const BINARY = '${binary}';`);
+    lines.push(`const ENV_OVERRIDE = process.env['${envVar}'];`);
+    lines.push(`const EFFECTIVE_BINARY = ENV_OVERRIDE ?? BINARY;`);
+    lines.push('');
+    lines.push(`/** Assert the required binary is available on PATH before any calls are made. */`);
+    lines.push(`function assertBinaryAvailable(): void {`);
+    lines.push(`  const check = spawnSync('which', [EFFECTIVE_BINARY], { encoding: 'utf-8' });`);
+    lines.push(`  if (check.status !== 0) {`);
+    lines.push(`    // Fallback: try --version directly (useful when 'which' itself is absent)`);
+    lines.push(`    const direct = spawnSync(EFFECTIVE_BINARY, ['--version'], { encoding: 'utf-8' });`);
+    lines.push(`    if (direct.status !== 0 && direct.error) {`);
+    lines.push(`      throw new Error(\`Required binary \${EFFECTIVE_BINARY} not found on PATH. ` +
+        `Install it or update ${envVar} env var.\`);`);
+    lines.push(`    }`);
+    lines.push(`  }`);
+    lines.push(`}`);
+    lines.push('');
+    lines.push(`// Run at module load — catches missing-binary errors at app boot.`);
+    lines.push(`assertBinaryAvailable();`);
+    return lines.join('\n');
+}
+/**
+ * Generate the TypeScript interface for the executable client type.
+ *
+ * Dotted entries (`Subcommand.action`) → typed `(...args: unknown[]) => unknown` method.
+ * Bare entries (`EntityName`) → typed `(...args: unknown[]) => unknown` method (passthrough).
+ *
+ * Unlike the library emitter, subprocess calls are synchronous (`spawnSync`), so
+ * the return type is `unknown` (not `Promise<unknown>`). Callers may wrap in a
+ * Promise if they need async composition; the underlying I/O is blocking.
+ */
+function generateInterface(interfaceName, selectEntries) {
+    const lines = [];
+    lines.push(`export type ${interfaceName}Client = {`);
+    const seen = new Set();
+    for (const entry of selectEntries) {
+        if (seen.has(entry))
+            continue;
+        seen.add(entry);
+        const { head, tail } = parseSelectEntry(entry);
+        if (tail === undefined) {
+            // Bare entity — passthrough all args as JSON-encoded CLI arguments.
+            lines.push(`  /** Invokes: spawnSync(binary, ['${head.toLowerCase()}', ...JSON-encoded args]) */`);
+            lines.push(`  ${head}(...args: unknown[]): unknown;`);
+        }
+        else {
+            // Dotted operation — subcommand + action dispatch.
+            lines.push(`  /** Invokes: spawnSync(binary, ['${head.toLowerCase()}', '${tail}', ...JSON-encoded args]) */`);
+            lines.push(`  ${tail}(...args: unknown[]): unknown;`);
+        }
+    }
+    lines.push('};');
+    return lines.join('\n');
+}
+/**
+ * Generate the client constant — spawnSync-backed implementation.
+ *
+ * Each method:
+ *   1. JSON-encodes each argument via JSON.stringify.
+ *   2. Calls spawnSync with [subcommand, action, ...encodedArgs] (dotted) or
+ *      [entityname, ...encodedArgs] (bare).
+ *   3. On non-zero exit, throws Error('<binary> <subcommand>: <stderr>').
+ *   4. Parses stdout as JSON and returns the result.
+ */
+function generateClientConstant(clientName, interfaceName, selectEntries) {
+    const lines = [];
+    lines.push(`export const ${clientName}Client: ${interfaceName}Client = {`);
+    const seen = new Set();
+    for (const entry of selectEntries) {
+        if (seen.has(entry))
+            continue;
+        seen.add(entry);
+        const { head, tail } = parseSelectEntry(entry);
+        if (tail === undefined) {
+            // Bare entity passthrough — proxy all args as JSON-encoded CLI arguments.
+            const subcommand = head.toLowerCase();
+            lines.push(`  ${head}(...args: unknown[]): unknown {`);
+            lines.push(`    const encodedArgs = args.map((a) => JSON.stringify(a));`);
+            lines.push(`    const result = spawnSync(EFFECTIVE_BINARY, ['${subcommand}', ...encodedArgs], { encoding: 'utf-8' });`);
+            lines.push(`    if (result.status !== 0) {`);
+            lines.push(`      throw new Error(\`\${EFFECTIVE_BINARY} ${subcommand}: \${result.stderr}\`);`);
+            lines.push(`    }`);
+            lines.push(`    return JSON.parse(result.stdout);`);
+            lines.push(`  },`);
+        }
+        else {
+            // Dotted operation — subcommand (head) + action (tail) dispatch.
+            const subcommand = head.toLowerCase();
+            lines.push(`  ${tail}(...args: unknown[]): unknown {`);
+            lines.push(`    const encodedArgs = args.map((a) => JSON.stringify(a));`);
+            lines.push(`    const result = spawnSync(EFFECTIVE_BINARY, ['${subcommand}', '${tail}', ...encodedArgs], { encoding: 'utf-8' });`);
+            lines.push(`    if (result.status !== 0) {`);
+            lines.push(`      throw new Error(\`\${EFFECTIVE_BINARY} ${subcommand}: \${result.stderr}\`);`);
+            lines.push(`    }`);
+            lines.push(`    return JSON.parse(result.stdout);`);
+            lines.push(`  },`);
+        }
+    }
+    lines.push('};');
+    return lines.join('\n');
+}
+// ─── Executable emitter ───────────────────────────────────────────────────────
+/**
+ * Executable-runtime emitter implementation.
+ *
+ * One call to `emit()` processes a single `import:` entry and produces
+ * one client file under `clients/<provider-filename>.ts`.
+ * No server-bind file is emitted (subprocess providers have no server).
+ */
+export class ExecutableRuntimeEmitter {
+    topology = 'executable';
+    async emit(ctx) {
+        const { importEntry, resolved, factory } = ctx;
+        const selectEntries = importEntry.select ?? [];
+        // Resolve binary name: config?.binary → factory.name.toLowerCase()
+        const binary = resolveBinaryName(factory);
+        // Derive naming from the import's `from:` field.
+        const fileName = toFileName(importEntry.from);
+        const clientName = toClientName(importEntry.from);
+        const interfaceName = toInterfaceName(importEntry.from);
+        // File path relative to outputDir.
+        const relFilePath = `clients/${fileName}.ts`;
+        // Build file header.
+        const headerLines = [
+            '// FACTORY-EMITTED — DO NOT EDIT (R8)',
+            `// Generated by executable-runtime emitter — V2 Phase 3`,
+            `// Provider: ${importEntry.from} (${resolved.source}) via factory: ${factory.name}`,
+            `// Binary: ${binary}`,
+            '',
+        ];
+        // Build availability check block (includes `import { spawnSync }` and constant declaration).
+        const availabilityBlock = generateBinaryAvailabilityCheck(binary);
+        // Build interface.
+        const interfaceBlock = generateInterface(interfaceName, selectEntries);
+        // Build client constant.
+        const constantBlock = generateClientConstant(clientName, interfaceName, selectEntries);
+        // Assemble file.
+        const parts = [
+            ...headerLines,
+            availabilityBlock,
+            '',
+            interfaceBlock,
+            '',
+            constantBlock,
+            '',
+        ];
+        const content = parts.join('\n');
+        // Build the import entry for the consumer's controller file.
+        const consumerImport = {
+            from: `./clients/${fileName}`,
+            specifier: `${clientName}Client`,
+        };
+        // Notes: warnings + deployment instance hint.
+        const notes = [];
+        if (selectEntries.length === 0) {
+            notes.push(`Warning: import entry from '${importEntry.from}' has empty select: — no client members emitted.`);
+        }
+        // Deployment instance hint — provider lands in infrastructure category.
+        notes.push(`Deployment hint: add '${importEntry.from}' to deployments.<env>.instances.infrastructure` +
+            ` with config: { binary: '${binary}' }. No process lifecycle; just a binary path requirement.`);
+        const deploymentSuggestion = {
+            provider: importEntry.from,
+            consumerComponent: ctx.consumerComponent?.name,
+            category: 'infrastructure',
+            key: clientName,
+            config: {
+                binary,
+            },
+            factory: factory.name,
+            topology: 'executable',
+        };
+        return {
+            files: [{ path: relFilePath, content }],
+            imports: [consumerImport],
+            notes,
+            deploymentSuggestion,
+        };
+    }
+}
+//# sourceMappingURL=executable.js.map

package/dist/realize/runtime-emitters/executable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executable.js","sourceRoot":"","sources":["../../../src/realize/runtime-emitters/executable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAQH,gFAAgF;AAEhF;;;;GAIG;AACH,SAAS,gBAAgB,CAAC,KAAa;IACrC,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,QAAQ,KAAK,CAAC,CAAC,EAAE,CAAC;QACpB,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAC1C,CAAC;IACD,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC;QAC9B,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC;KAChC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,OAAO,CAAC,QAAgB;IAC/B,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAClE,OAAO,UAAU;SACd,OAAO,CAAC,iBAAiB,EAAE,OAAO,CAAC;SACnC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC;SAC9B,IAAI,EAAE;SACN,KAAK,CAAC,GAAG,CAAC;SACV,MAAM,CAAC,OAAO,CAAC;SACf,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,SAAS,YAAY,CAAC,QAAgB;IACpC,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,eAAe,CAAC;IAC/C,OAAO,CACL,KAAK,CAAC,CAAC,CAAE;QACT,KAAK;aACF,KAAK,CAAC,CAAC,CAAC;aACR,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;aAClD,IAAI,CAAC,EAAE,CAAC,CACZ,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,QAAgB;IACvC,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC3E,CAAC;AAED;;;GAGG;AACH,SAAS,UAAU,CAAC,QAAgB;IAClC,OAAO,OAAO,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACrC,CAAC;AAED,iFAAiF;AAEjF;;;;;;;;GAQG;AACH,SAAS,iBAAiB,CAAC,OAAyC;IAClE,MAAM,YAAY,GAAI,OAAO,CAAC,UAA2D;QACvF,EAAE,MAAM,EAAE,MAAM,CAAC;IACnB,IAAI,YAAY,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChF,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;AACpC,CAAC;AAED,iFAAiF;AAEjF;;;;;;;;GAQG;AACH,SAAS,+BAA+B,CAAC,MAAc;IACrD,MAAM,MAAM,GAAG,aAAa,MAAM,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC,OAAO,CAAC;IACnF,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC;IACzD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,mBAAmB,MAAM,IAAI,CAAC,CAAC;IAC1C,KAAK,CAAC,IAAI,CAAC,qCAAqC,MAAM,KAAK,CAAC,CAAC;IAC7D,KAAK,CAAC,IAAI,CAAC,kDAAkD,CAAC,CAAC;IAC/D,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,mFAAmF,CAAC,CAAC;IAChG,KAAK,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC;IACvD,KAAK,CAAC,IAAI,CAAC,gFAAgF,CAAC,CAAC;IAC7F,KAAK,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;IAC1C,KAAK,CAAC,IAAI,CAAC,gFAAgF,CAAC,CAAC;IAC7F,KAAK,CAAC,IAAI,CAAC,uFAAuF,CAAC,CAAC;IACpG,KAAK,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAC;IAC7D,KAAK,CAAC,IAAI,CACR,kFAAkF;QAChF,wBAAwB,MAAM,eAAe,CAChD,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,oEAAoE,CAAC,CAAC;IACjF,KAAK,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IACvC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,iBAAiB,CACxB,aAAqB,EACrB,aAAuB;IAEvB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,eAAe,aAAa,YAAY,CAAC,CAAC;IAErD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,SAAS;QAC9B,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChB,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;QAC/C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,oEAAoE;YACpE,KAAK,CAAC,IAAI,CACR,sCAAsC,IAAI,CAAC,WAAW,EAAE,8BAA8B,CACvF,CAAC;YACF,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,gCAAgC,CAAC,CAAC;QACxD,CAAC;aAAM,CAAC;YACN,mDAAmD;YACnD,KAAK,CAAC,IAAI,CACR,sCAAsC,IAAI,CAAC,WAAW,EAAE,OAAO,IAAI,8BAA8B,CAClG,CAAC;YACF,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,gCAAgC,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,sBAAsB,CAC7B,UAAkB,EAClB,aAAqB,EACrB,aAAuB;IAEvB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,gBAAgB,UAAU,WAAW,aAAa,YAAY,CAAC,CAAC;IAE3E,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,SAAS;QAC9B,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChB,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;QAC/C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,0EAA0E;YAC1E,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;YACtC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,iCAAiC,CAAC,CAAC;YACvD,KAAK,CAAC,IAAI,CAAC,6DAA6D,CAAC,CAAC;YAC1E,KAAK,CAAC,IAAI,CACR,oDAAoD,UAAU,6CAA6C,CAC5G,CAAC;YACF,KAAK,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;YAC7C,KAAK,CAAC,IAAI,CACR,gDAAgD,UAAU,yBAAyB,CACpF,CAAC;YACF,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACpB,KAAK,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;YACpD,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrB,CAAC;aAAM,CAAC;YACN,iEAAiE;YACjE,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;YACtC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,iCAAiC,CAAC,CAAC;YACvD,KAAK,CAAC,IAAI,CAAC,6DAA6D,CAAC,CAAC;YAC1E,KAAK,CAAC,IAAI,CACR,oDAAoD,UAAU,OAAO,IAAI,6CAA6C,CACvH,CAAC;YACF,KAAK,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;YAC7C,KAAK,CAAC,IAAI,CACR,gDAAgD,UAAU,yBAAyB,CACpF,CAAC;YACF,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACpB,KAAK,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;YACpD,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,iFAAiF;AAEjF;;;;;;GAMG;AACH,MAAM,OAAO,wBAAwB;IAC1B,QAAQ,GAAG,YAAqB,CAAC;IAE1C,KAAK,CAAC,IAAI,CAAC,GAA0B;QACnC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC;QAC/C,MAAM,aAAa,GAAG,WAAW,CAAC,MAAM,IAAI,EAAE,CAAC;QAE/C,mEAAmE;QACnE,MAAM,MAAM,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAE1C,iDAAiD;QACjD,MAAM,QAAQ,GAAG,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC9C,MAAM,UAAU,GAAG,YAAY,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAClD,MAAM,aAAa,GAAG,eAAe,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAExD,mCAAmC;QACnC,MAAM,WAAW,GAAG,WAAW,QAAQ,KAAK,CAAC;QAE7C,qBAAqB;QACrB,MAAM,WAAW,GAAa;YAC5B,uCAAuC;YACvC,yDAAyD;YACzD,gBAAgB,WAAW,CAAC,IAAI,KAAK,QAAQ,CAAC,MAAM,kBAAkB,OAAO,CAAC,IAAI,EAAE;YACpF,cAAc,MAAM,EAAE;YACtB,EAAE;SACH,CAAC;QAEF,6FAA6F;QAC7F,MAAM,iBAAiB,GAAG,+BAA+B,CAAC,MAAM,CAAC,CAAC;QAElE,mBAAmB;QACnB,MAAM,cAAc,GAAG,iBAAiB,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;QAEvE,yBAAyB;QACzB,MAAM,aAAa,GAAG,sBAAsB,CAAC,UAAU,EAAE,aAAa,EAAE,aAAa,CAAC,CAAC;QAEvF,iBAAiB;QACjB,MAAM,KAAK,GAAa;YACtB,GAAG,WAAW;YACd,iBAAiB;YACjB,EAAE;YACF,cAAc;YACd,EAAE;YACF,aAAa;YACb,EAAE;SACH,CAAC;QAEF,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEjC,6DAA6D;QAC7D,MAAM,cAAc,GAAG;YACrB,IAAI,EAAE,aAAa,QAAQ,EAAE;YAC7B,SAAS,EAAE,GAAG,UAAU,QAAQ;SACjC,CAAC;QAEF,8CAA8C;QAC9C,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CACR,+BAA+B,WAAW,CAAC,IAAI,kDAAkD,CAClG,CAAC;QACJ,CAAC;QAED,wEAAwE;QACxE,KAAK,CAAC,IAAI,CACR,yBAAyB,WAAW,CAAC,IAAI,iDAAiD;YACxF,4BAA4B,MAAM,4DAA4D,CACjG,CAAC;QAEF,MAAM,oBAAoB,GAAG;YAC3B,QAAQ,EAAE,WAAW,CAAC,IAAI;YAC1B,iBAAiB,EAAG,GAAG,CAAC,iBAAyB,EAAE,IAAI;YACvD,QAAQ,EAAE,gBAAyB;YACnC,GAAG,EAAE,UAAU;YACf,MAAM,EAAE;gBACN,MAAM;aACP;YACD,OAAO,EAAE,OAAO,CAAC,IAAI;YACrB,QAAQ,EAAE,YAAqB;SAChC,CAAC;QAEF,OAAO;YACL,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;YACvC,OAAO,EAAE,CAAC,cAAc,CAAC;YACzB,KAAK;YACL,oBAAoB;SACrB,CAAC;IACJ,CAAC;CACF"}

package/dist/realize/runtime-emitters/library.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Library-runtime emitter — V2 Phase 3, Round 1.
+ *
+ * Handles `topology: 'library'` factories: providers that are consumed
+ * as in-process imports, with no deployment instance entry.
+ *
+ * For each `import:` entry the consumer declares, this emitter produces:
+ *   clients/<provider-name>.ts   — typed client module
+ *
+ * The typed client module:
+ *   - Exports a `<ProviderName>Client` TypeScript interface matching
+ *     the selected operations from `import.select`.
+ *   - Exports a `<providerName>Client` constant that implements the
+ *     interface by delegating to the resolved provider:
+ *       * source = 'local'  → relative import to the provider's module.
+ *       * source = 'npm'    → `import { X } from '<package-specifier>'`.
+ *       * source = 'registry-*' → TODO comment + runtime throw (Round 1).
+ *
+ * The consuming controller (SalesReportController.ts, emitted by the
+ * per-action-emitter's mechanical scaffold) imports this client module
+ * and receives the client via constructor injection.
+ *
+ * --- Select grammar ---
+ *
+ * `import.select` entries follow two forms (V2 D2 resolution):
+ *   - Dotted: `Charge.create`  → typed function for the specific operation.
+ *   - Bare:   `AuthService`    → re-export of the entity's interface.
+ *
+ * Both forms share the same file; the emitter deduplicates by head entity.
+ *
+ * --- Round 1 limitations ---
+ *
+ * - No actual operation signature lookup (operations are typed as
+ *   `(...args: unknown[]) => Promise<unknown>` unless the spec is provided
+ *   and the target operation can be located). Exact signatures land in
+ *   Round 2 when the resolver wires in full cross-spec type lookup.
+ * - Registry sources (`registry-component`, `registry-factory`) emit a
+ *   TODO comment and a `throw` for the client constant; they compile but
+ *   blow up at runtime until Round 2 fills in the registry resolver.
+ */
+import type { RuntimeEmitter, RuntimeEmitterContext, RuntimeEmitterResult } from './dispatcher.js';
+/**
+ * Library-runtime emitter implementation.
+ *
+ * One call to `emit()` processes a single `import:` entry and produces
+ * one client file under `clients/<provider-filename>.ts`.
+ */
+export declare class LibraryRuntimeEmitter implements RuntimeEmitter {
+    readonly topology: "library";
+    emit(ctx: RuntimeEmitterContext): Promise<RuntimeEmitterResult>;
+}
+//# sourceMappingURL=library.d.ts.map

package/dist/realize/runtime-emitters/library.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"library.d.ts","sourceRoot":"","sources":["../../../src/realize/runtime-emitters/library.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,iBAAiB,CAAC;AAyQzB;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,cAAc;IAC1D,QAAQ,CAAC,QAAQ,EAAG,SAAS,CAAU;IAEjC,IAAI,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CA+EtE"}