@specverse/engines 6.39.3 → 6.40.7

package/dist/realize/per-owner-emit.js

@@ -0,0 +1,351 @@
+/**
+ * Per-owner LLM emit hook — Phase 1 of the 2026-05-11-PER-OWNER-VS-PER-ACTION
+ * proposal.
+ *
+ * Sibling of `per-action-llm-emit.ts`. SAME structural-validator and
+ * parse-check infrastructure, DIFFERENT granularity: one LLM call per
+ * controller / service instead of one per action. Restores the
+ * class-level context (constructor injection, shared helpers, sibling
+ * methods) that per-action emission engineered out and that surfaced
+ * empirically as the 31% LLM-decline rate on idle-meta sonnet (the
+ * LLM correctly refused to invent imports it couldn't see were
+ * available).
+ *
+ * Three quality gates run on the emitted file:
+ *   1. Markdown extraction — pull the ```typescript fenced block out
+ *      of the LLM response. Empty / missing block → null (caller
+ *      falls through to per-action emit OR engine γ-stub).
+ *   2. Structural preservation (DR3) — every pre-baked snippet from
+ *      every action's per-step matches must appear verbatim somewhere
+ *      in the emitted file. A rewritten snippet is a loud failure;
+ *      we throw with a diff.
+ *   3. esbuild parse check — the file must be syntactically valid TS.
+ *      Surgical retry once on parse failure; if it fails again we
+ *      return null (caller falls through).
+ *
+ * The realize-owner.prompt.yaml asset ships at:
+ * `@specverse/assets/prompts/core/standard/default/realize-owner.prompt.yaml`.
+ * Until assets is republished with it, a filesystem fallback under
+ * `specverse-self/assets/` is searched.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+import yaml from 'js-yaml';
+import { loadPrompt, runPrompt as runPromptFn, assembleSystem, assembleUser, } from '../ai/prompt-runner.js';
+import { validateLlmOutputPreservesConventions, } from './structural-validator.js';
+import { extractTypescriptBlock } from './per-action-llm-emit.js';
+const require = createRequire(import.meta.url);
+/**
+ * Build a {@link PerOwnerEmitFn} for use in per-owner realize emission.
+ *
+ * Returned function:
+ *   1. Builds the prompt input from the per-owner request.
+ *   2. Calls runPrompt({ operation: 'realize-owner', ... }).
+ *   3. Extracts the ```typescript block from the response.
+ *   4. Runs the structural validator (DR3); throws on rewrite.
+ *   5. Runs an esbuild parse check; surgical-retries once on failure.
+ *   6. Returns the file contents string, or null when all attempts
+ *      fail (caller falls through).
+ */
+export function createRealizeOwnerLlmEmit(opts = {}) {
+    const runPrompt = opts.runPromptOverride ?? runPromptFn;
+    const loadPromptResolved = opts.loadPromptOverride ?? loadRealizeOwnerPrompt;
+    const parseCheck = opts.parseCheckOverride ?? esbuildFileParseCheck;
+    return async (request) => {
+        // 1. Pre-bake snippets across all actions for the structural
+        //    validator. Each matched step from any action contributes.
+        const prebakedSnippets = [];
+        for (const action of request.actions) {
+            action.perStepMatches.forEach((match, idx) => {
+                if (match?.matched && match.call) {
+                    prebakedSnippets.push({
+                        stepNum: idx + 1,
+                        stepText: action.spec.steps[idx] ?? '',
+                        snippet: match.call,
+                    });
+                }
+            });
+        }
+        // 2. Build prompt values.
+        const promptValues = buildPromptValues(request);
+        // 3. Surgical retry loop (cap at 1).
+        const maxAttempts = opts.disableSurgicalRetry ? 1 : 2;
+        let lastParseError = null;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            const userPrefix = lastParseError
+                ? buildSurgicalRetryPrefix(lastParseError, request.ownerName)
+                : '';
+            let runResult;
+            try {
+                // Per-owner calls produce whole-file emissions (5-15K tokens
+                // per call vs 1.5-3K per-action) and routinely run 60-180s
+                // for big owners on sonnet. The default 5-minute timeout was
+                // sufficient for per-action but cut off large per-owner emits
+                // (the 2026-05-11 trial saw GamesV3Controller, 6 actions,
+                // time out at exactly 300s). Bump the default to 15min for
+                // per-owner; callers can still tighten via opts.timeoutMs.
+                const timeoutMs = opts.timeoutMs ?? 900_000;
+                const runOpts = {
+                    operation: 'realize-owner',
+                    values: promptValues,
+                    model: opts.model,
+                    timeoutMs,
+                    userPrefix,
+                };
+                runResult = await callRunPromptWithFallback(runPrompt, runOpts, loadPromptResolved);
+            }
+            catch (e) {
+                if (process.env.SPECVERSE_VERBOSE) {
+                    const cls = (e && e.constructor && e.constructor.name) || 'Error';
+                    const msg = (e && e.message) || String(e);
+                    const head = String(msg).slice(0, 240).replace(/\s+/g, ' ');
+                    console.error(`   ✗ per-owner LLM emit threw for ${request.ownerName} [${cls}]: ${head}`);
+                }
+                return null;
+            }
+            // 4. Extract the ```typescript fenced block.
+            const fileContents = extractTypescriptBlock(runResult.text);
+            if (!fileContents || fileContents.trim().length === 0) {
+                if (process.env.SPECVERSE_VERBOSE) {
+                    const reason = fileContents === undefined || fileContents === null
+                        ? 'no typescript code block in LLM response'
+                        : 'typescript block was empty';
+                    console.error(`   ✗ per-owner LLM emit empty for ${request.ownerName}: ${reason}`);
+                }
+                return null;
+            }
+            // 5. Structural validator — DR3. A rewritten pre-baked snippet
+            //    is a LOUD failure (not a silent retry).
+            const structural = validateLlmOutputPreservesConventions(fileContents, prebakedSnippets);
+            if (structural.ok === false) {
+                throw new Error(`[realize-owner] structural-preservation failed for ${request.ownerName}:\n${structural.reason}`);
+            }
+            // 6. esbuild parse check — surgical retry once on parse failure.
+            const parseError = await parseCheck(fileContents);
+            if (parseError === null) {
+                // All gates green — return the file.
+                return fileContents;
+            }
+            lastParseError = parseError;
+        }
+        // Exhausted retries — fall through.
+        if (process.env.SPECVERSE_VERBOSE) {
+            const head = String(lastParseError ?? 'unknown').slice(0, 240).replace(/\s+/g, ' ');
+            console.error(`   ✗ per-owner LLM emit parse-failed after ${maxAttempts} attempt(s) for ${request.ownerName}: ${head}`);
+        }
+        return null;
+    };
+}
+// ─── Prompt loading + assets fallback ────────────────────────────────
+/** Default prompt loader. Tries the installed @specverse/assets path
+ *  first; falls back to the in-repo specverse-self/assets/ tree for
+ *  dev cycles where assets isn't yet republished. Mirrors the
+ *  per-action emitter's fallback strategy.  */
+function loadRealizeOwnerPrompt() {
+    // Installed path: shipped from @specverse/assets via loadPrompt.
+    try {
+        return loadPrompt('realize-owner');
+    }
+    catch (e) {
+        // Try filesystem fallbacks below.
+    }
+    const fallback = loadRealizeOwnerPromptFromFallback();
+    if (fallback)
+        return fallback;
+    throw new Error('realize-owner.prompt.yaml not found in @specverse/assets nor the ' +
+        'specverse-self/assets/ filesystem fallback. Has the assets ' +
+        'package been republished since 2026-05-11?');
+}
+/** Filesystem fallback search for the realize-owner prompt. Mirrors
+ *  per-action-llm-emit.ts:loadRealizeActionPromptFromFallback's three-
+ *  tier search: @specverse/assets package path, engine-bundled assets,
+ *  worktree-sibling specverse-self/assets. */
+export function loadRealizeOwnerPromptFromFallback() {
+    const candidates = [];
+    // 1. @specverse/assets package (covers the post-publish case).
+    try {
+        const pkg = require.resolve('@specverse/assets/package.json');
+        candidates.push(join(dirname(pkg), 'prompts/core/standard/default/realize-owner.prompt.yaml'), join(dirname(pkg), 'prompts/core/standard/v9/realize-owner.prompt.yaml'));
+    }
+    catch {
+        /* assets not installed */
+    }
+    // 2. Engine-bundled assets (engines ≤ 6.0.2-style layouts).
+    try {
+        const enginesPkg = require.resolve('@specverse/engines/package.json');
+        candidates.push(join(dirname(enginesPkg), 'assets/prompts/core/standard/default/realize-owner.prompt.yaml'), join(dirname(enginesPkg), 'assets/prompts/core/standard/v9/realize-owner.prompt.yaml'));
+    }
+    catch {
+        /* engines not installed at this path */
+    }
+    // 3. @specverse/self package (covers the post-publish case where
+    //    self has the prompts bundled but @specverse/assets doesn't yet).
+    //    Per-owner ships to specverse-self/assets/ first during the trial.
+    try {
+        const selfPkg = require.resolve('@specverse/self/package.json');
+        candidates.push(join(dirname(selfPkg), 'assets/prompts/core/standard/default/realize-owner.prompt.yaml'), join(dirname(selfPkg), 'assets/prompts/core/standard/v9/realize-owner.prompt.yaml'));
+    }
+    catch {
+        /* self not installed at this path */
+    }
+    // 4. Worktree fallback — specverse-self lives next to specverse-engines.
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        candidates.push(resolve(here, '../../../../specverse-self/assets/prompts/core/standard/default/realize-owner.prompt.yaml'), resolve(here, '../../../../specverse-self/assets/prompts/core/standard/v9/realize-owner.prompt.yaml'), resolve(here, '../../../../../specverse-self/assets/prompts/core/standard/default/realize-owner.prompt.yaml'), resolve(here, '../../../../../specverse-self/assets/prompts/core/standard/v9/realize-owner.prompt.yaml'));
+    }
+    catch {
+        /* import.meta.url unavailable */
+    }
+    for (const p of candidates) {
+        if (existsSync(p)) {
+            try {
+                return yaml.load(readFileSync(p, 'utf-8'));
+            }
+            catch {
+                /* try next */
+            }
+        }
+    }
+    return null;
+}
+/** Wrap runPrompt with the assets-fallback prompt-loading strategy.
+ *  Mirrors per-action-llm-emit's same-named helper: first try
+ *  runPrompt's own loadPrompt path; on `prompt file not found`,
+ *  fall back to the filesystem-loaded prompt and call ai-sdk
+ *  generateText directly so we don't need a `prompt: PromptYaml`
+ *  field on RunPromptOptions. */
+async function callRunPromptWithFallback(runPromptImpl, opts, fallbackLoader) {
+    // First try: let runPrompt do its own loadPrompt.
+    try {
+        return await runPromptImpl(opts);
+    }
+    catch (e) {
+        const msg = e?.message ?? String(e);
+        if (!/prompt file not found for "realize-owner"/i.test(msg)) {
+            throw e;
+        }
+    }
+    // Second try: load via fallback + call ai-sdk directly.
+    const prompt = fallbackLoader();
+    const system = assembleSystem(prompt);
+    const baseUser = assembleUser(prompt, opts.values);
+    const user = (opts.userPrefix || '') + baseUser;
+    if (typeof opts.onAssembled === 'function') {
+        opts.onAssembled({ system, user });
+    }
+    const aiSdk = await import('ai');
+    const { resolveModel } = await import('../ai/model-resolver.js');
+    const model = opts.model ?? resolveModel({ ...(opts.modelOptions ?? {}), timeout: opts.timeoutMs ?? 300_000 });
+    const t0 = Date.now();
+    const result = await aiSdk.generateText({
+        model,
+        system,
+        prompt: user,
+        abortSignal: AbortSignal.timeout(opts.timeoutMs ?? 300_000),
+    });
+    const duration_ms = Date.now() - t0;
+    return {
+        text: result.text,
+        tokens: {
+            input: result.usage?.inputTokens?.total ?? null,
+            output: result.usage?.outputTokens?.total ?? null,
+        },
+        duration_ms,
+        system,
+        user,
+        providerId: model.provider,
+        modelId: model.modelId,
+    };
+}
+// ─── Prompt input builder ────────────────────────────────────────────
+/** Build the prompt-values map that the realize-owner.prompt.yaml
+ *  user template references. */
+function buildPromptValues(request) {
+    const ownerSpecYaml = yamlDumpOwner(request.ownerSpec, request.ownerName);
+    const perActionScaffolding = buildPerActionScaffolding(request.actions);
+    return {
+        ownerName: request.ownerName,
+        ownerKind: request.ownerKind,
+        ownerSpec: ownerSpecYaml,
+        perActionScaffolding,
+        availableClients: request.availableClients ?? '(none)',
+        availableCapabilities: request.availableCapabilities ?? '(none — only `input: any` is available)',
+        processContext: request.processContext ?? '(no related processes)',
+    };
+}
+/** Render the owner's spec body as YAML. Top-level key = the owner
+ *  name; nested body = the spec object (actions / operations / etc.). */
+function yamlDumpOwner(ownerSpec, ownerName) {
+    return yaml.dump({ [ownerName]: ownerSpec }, { lineWidth: 100, noRefs: true });
+}
+/** Build the per-action scaffolding block. One section per action,
+ *  listing its steps with [PRE-BAKED] / [WRITE] markers. */
+function buildPerActionScaffolding(actions) {
+    if (actions.length === 0)
+        return '(no actions on this owner)';
+    const sections = [];
+    for (const action of actions) {
+        sections.push(`### ${action.actionName}`);
+        if (!action.spec.steps?.length) {
+            sections.push('  (no steps declared — emit a bare body that fulfils the spec)');
+            sections.push('');
+            continue;
+        }
+        for (let i = 0; i < action.spec.steps.length; i++) {
+            const stepText = action.spec.steps[i] ?? '';
+            const match = action.perStepMatches[i];
+            if (match?.matched && match.call) {
+                sections.push(`  ${i + 1}. [PRE-BAKED] "${stepText}" →`);
+                const snippetLines = match.call.split('\n');
+                for (const snippetLine of snippetLines) {
+                    sections.push(`       ${snippetLine}`);
+                }
+            }
+            else {
+                sections.push(`  ${i + 1}. [WRITE]      "${stepText}"`);
+            }
+        }
+        sections.push('');
+    }
+    return sections.join('\n');
+}
+/** File-level esbuild parse check. Distinct from
+ *  per-action-llm-emit's `esbuildParseCheck` which wraps the body in
+ *  a function (correct for action-body emission but wrong for
+ *  whole-file emission with top-of-file imports). Here we parse the
+ *  file as a TS module directly. Returns null on success, an error
+ *  message string on failure. */
+async function esbuildFileParseCheck(fileContents) {
+    try {
+        const esbuild = await import('esbuild');
+        await esbuild.transform(fileContents, {
+            loader: 'ts',
+            format: 'esm',
+            target: 'es2022',
+        });
+        return null;
+    }
+    catch (err) {
+        const msg = err?.errors?.[0]?.text || err?.message || 'unknown parse error';
+        return msg;
+    }
+}
+/** Render the surgical-retry prefix that frames the parse error for
+ *  the LLM. Reuses the per-action-llm-emit convention. */
+function buildSurgicalRetryPrefix(parseError, ownerName) {
+    const trimmed = parseError.split('\n').slice(0, 4).join('\n');
+    return [
+        `Your previous emission for ${ownerName} failed an esbuild parse check:`,
+        '',
+        trimmed,
+        '',
+        'Re-emit the entire file with the parse error corrected. Preserve',
+        'all [PRE-BAKED] snippets verbatim. If a specific action cannot be',
+        'implemented coherently, use the γ-stub form for THAT action while',
+        'keeping the others fully implemented.',
+        '',
+    ].join('\n');
+}
+//# sourceMappingURL=per-owner-emit.js.map

package/dist/realize/per-owner-emit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"per-owner-emit.js","sourceRoot":"","sources":["../../src/realize/per-owner-emit.ts"],"names":[],"mappings":"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"}

package/dist/realize/per-owner-runner.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Per-owner realize runner — Phase 1 of the 2026-05-11-PER-OWNER-VS-PER-ACTION
+ * proposal.
+ *
+ * Sibling of `per-action-runner.ts`. SAME spec-walking + owner-grouping
+ * logic, DIFFERENT emission granularity: instead of calling
+ * `emitActionBody` once per action, this runner calls the per-owner
+ * LLM emit hook ONCE per owner and writes the resulting whole-file
+ * content as `<Owner>.ai.ts`.
+ *
+ * Why this exists: the per-action emitter (Realize L3 Phase 3) gave
+ * the LLM narrow context — one action's steps, no class shell, no
+ * sibling methods, no manifest capabilities. Empirically on
+ * idle-meta sonnet, that produced 29 of 94 actions as throw-stubs
+ * because the LLM correctly refused to invent imports it couldn't
+ * see were available. Per-owner restores the holistic context.
+ *
+ * Same `<Owner>.ai.ts` output shape (exported async functions per
+ * action) → no consumer-interface change. The downstream controller
+ * still does `import * as aiBehaviors from '../behaviors/X.ai.js'`.
+ */
+import { buildAvailableClientsByOwner } from './per-action-runner.js';
+import type { MatcherFn, SharedConvention } from './per-action-emitter.js';
+import type { PerOwnerEmitFn } from './per-owner-emit.js';
+/** Options for {@link runPerOwnerEmission}. */
+export interface RunPerOwnerEmissionOptions {
+    /** Full inferred spec. */
+    spec: any;
+    /** Output directory — `.ai.ts` files go under `${outputDir}/backend/src/behaviors/`. */
+    outputDir: string;
+    /** Convention matcher (default: `matchAgainstConventions`). */
+    matcher?: MatcherFn;
+    /** Convention array for the matcher. */
+    conventions?: ReadonlyArray<SharedConvention>;
+    /** Per-owner LLM emit hook. Required — the whole point of this
+     *  runner is to drive it once per owner. */
+    perOwnerEmit: PerOwnerEmitFn;
+    /** Pre-built availableClients map (from buildAvailableClientsByOwner). */
+    availableClientsByOwner?: Map<string, string>;
+    /** Manifest capability mappings text (NEW vs per-action runner).
+     *  Format: pre-rendered string listing each mapping, e.g.
+     *    "  - orm.client → PrismaClient (orms/prisma)\n  - jwt.signer → ..." */
+    availableCapabilities?: string;
+    /** Process context string per owner (optional). */
+    processContextByOwner?: Map<string, string>;
+    /** Skip the per-owner ✅ console.log lines (used by harness runs). */
+    silent?: boolean;
+    /** Test hook: don't write files to disk; just return the emission
+     *  result for assertion. */
+    dryRun?: boolean;
+}
+/** Result of {@link runPerOwnerEmission}. */
+export interface RunPerOwnerEmissionResult {
+    /** Per-owner emission records (file contents + outcome). */
+    owners: PerOwnerOutcome[];
+    /** Absolute paths of files written (empty when dryRun). */
+    filesWritten: string[];
+    /** Aggregate counters. */
+    totals: {
+        /** Number of owners walked. */
+        ownerCount: number;
+        /** Number of actions across all owners. */
+        actionCount: number;
+        /** Owners whose LLM emit produced a usable file. */
+        ownersEmittedByLLM: number;
+        /** Owners whose LLM emit failed; runner fell back to a
+         *  deterministic placeholder file. */
+        ownersFellBack: number;
+    };
+}
+/** Per-owner emission outcome. */
+export interface PerOwnerOutcome {
+    ownerName: string;
+    /** Number of actions on this owner. */
+    actionCount: number;
+    /** True when LLM produced a usable file. */
+    llmEmitted: boolean;
+    /** File contents written. Empty string when LLM declined entirely
+     *  and the runner emitted a deterministic placeholder. */
+    fileContents: string;
+}
+/**
+ * Run per-owner LLM emission across every controller / service the
+ * spec declares. For each owner:
+ *   1. Collect its actions and resolve per-step matcher results.
+ *   2. Call the perOwnerEmit hook with the whole owner's context.
+ *   3. Write the returned file contents to disk (or fall back to a
+ *      placeholder file containing one γ stub per action when emit
+ *      returned null).
+ */
+export declare function runPerOwnerEmission(opts: RunPerOwnerEmissionOptions): Promise<RunPerOwnerEmissionResult>;
+/** Build the availableCapabilities string consumed by the per-owner
+ *  prompt's `availableCapabilities` slot. Walks the manifest's
+ *  capabilityMappings and renders one line per mapping with a brief
+ *  hint about what the factory provides. Exported so the realize
+ *  caller can build it once and feed it to every owner.
+ *
+ *  Format example:
+ *    - orm.client      → PrismaORM (provides Prisma's typed query API)
+ *    - jwt.signer      → JsonWebToken (jsonwebtoken.sign / verify)
+ *    - event.bus       → InMemoryEventBus (publish / subscribe)
+ */
+export declare function buildAvailableCapabilitiesString(manifest: any): string;
+export { buildAvailableClientsByOwner };
+//# sourceMappingURL=per-owner-runner.d.ts.map

package/dist/realize/per-owner-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"per-owner-runner.d.ts","sourceRoot":"","sources":["../../src/realize/per-owner-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAEL,4BAA4B,EAE7B,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAGV,SAAS,EACT,gBAAgB,EAGjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EACV,cAAc,EAEf,MAAM,qBAAqB,CAAC;AAE7B,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,0BAA0B;IAC1B,IAAI,EAAE,GAAG,CAAC;IACV,wFAAwF;IACxF,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,wCAAwC;IACxC,WAAW,CAAC,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IAC9C;gDAC4C;IAC5C,YAAY,EAAE,cAAc,CAAC;IAC7B,0EAA0E;IAC1E,uBAAuB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C;;gFAE4E;IAC5E,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,mDAAmD;IACnD,qBAAqB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,qEAAqE;IACrE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;gCAC4B;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,6CAA6C;AAC7C,MAAM,WAAW,yBAAyB;IACxC,4DAA4D;IAC5D,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,2DAA2D;IAC3D,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,0BAA0B;IAC1B,MAAM,EAAE;QACN,+BAA+B;QAC/B,UAAU,EAAE,MAAM,CAAC;QACnB,2CAA2C;QAC3C,WAAW,EAAE,MAAM,CAAC;QACpB,oDAAoD;QACpD,kBAAkB,EAAE,MAAM,CAAC;QAC3B;8CACsC;QACtC,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAED,kCAAkC;AAClC,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,UAAU,EAAE,OAAO,CAAC;IACpB;8DAC0D;IAC1D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,0BAA0B,GAC/B,OAAO,CAAC,yBAAyB,CAAC,CA0GpC;AA4KD;;;;;;;;;;GAUG;AACH,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,GAAG,GAAG,MAAM,CAYtE;AAkBD,OAAO,EAAE,4BAA4B,EAAE,CAAC"}