@nac3/forge-cli 0.2.0-alpha.5 → 0.2.0-alpha.59z.118

package/dist/core/sq_resolver.js

@@ -0,0 +1,230 @@
+/**
+ * SQ rules resolver (alpha.59y.3).
+ *
+ * Given the current workflow step, returns the subset of SQ rules
+ * that apply, with their one-line title from docs/SQ.md.
+ *
+ * Source of truth:
+ *   docs/SQ_BY_STEP.yaml -- manual matrix (step -> rule_slugs)
+ *   docs/SQ.md           -- rule titles (parsed from ### headings)
+ *
+ * Output (renderActiveRulesBlock) goes into the workflow inject
+ * block so the LLM sees ONLY the rules that matter at the current
+ * step + the always-active cross-cutting rules. Keeps the prompt
+ * compact + relevant.
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/** docs/ lives at repo root; dist files run from dist/core; tsx
+ *  runs from src/core. Walk up until we find docs/SQ.md. */
+function resolveDocsDir() {
+    let cur = __dirname;
+    for (let i = 0; i < 8; i++) {
+        const candidate = path.join(cur, 'docs', 'SQ.md');
+        /* fs.existsSync would be nice but we are async; instead we
+         *  hop levels and let readFile fail later if not found. */
+        if (cur === path.parse(cur).root)
+            break;
+        cur = path.dirname(cur);
+    }
+    /* Fallback: cwd. */
+    return path.resolve(process.cwd(), 'docs');
+}
+const DOCS_DIR_HINTS = [
+    /* dist/core -> ../../docs (repo root) when running from source repo */
+    path.resolve(__dirname, '..', '..', 'docs'),
+    /* dist/core -> ../docs (when copy_qa_assets put docs alongside core) */
+    path.resolve(__dirname, '..', 'docs'),
+    /* src/core -> ../../docs */
+    path.resolve(__dirname, '..', '..', 'docs'),
+    /* cwd / docs */
+    path.resolve(process.cwd(), 'docs'),
+];
+async function readDoc(name) {
+    for (const dir of DOCS_DIR_HINTS) {
+        try {
+            const p = path.join(dir, name);
+            const s = await fs.readFile(p, 'utf-8');
+            return s;
+        }
+        catch { /* try next */ }
+    }
+    return null;
+}
+let _yamlCache = null;
+let _titlesCache = null;
+/** Parse our limited YAML subset (top-level keys with arrays of
+ *  strings). We control the file, so no need for a real YAML lib.
+ *  Lines starting with '#' are comments. */
+function parseYaml(text) {
+    const out = {};
+    let currentKey = null;
+    let currentArr = [];
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.replace(/\r/g, '');
+        /* Skip blank + comments. */
+        if (!line.trim() || line.trim().startsWith('#'))
+            continue;
+        /* Top-level key (no indent): `name:` */
+        if (/^[a-zA-Z0-9_]+:/.test(line)) {
+            if (currentKey)
+                out[currentKey] = currentArr;
+            currentKey = line.split(':')[0].trim();
+            currentArr = [];
+            continue;
+        }
+        /* Array entry: `  - "0.1"` */
+        const m = line.match(/^\s*-\s*"?([^"#]+)"?/);
+        if (m && currentKey) {
+            const val = m[1].trim();
+            if (val)
+                currentArr.push(val);
+        }
+    }
+    if (currentKey)
+        out[currentKey] = currentArr;
+    return out;
+}
+/** Parse `### N.N Title` headings from SQ.md, returns slug->title map. */
+function parseSqTitles(text) {
+    const m = new Map();
+    for (const line of text.split(/\r?\n/)) {
+        /* Match either `### 0.1 Title` or `### 14 Title` */
+        const r = line.match(/^###\s+(\d+(?:\.\d+)?)\s+(.+?)\s*$/);
+        if (r)
+            m.set(r[1], r[2].trim());
+        /* Also catch `## N. Title` (top-level section names). */
+        const r2 = line.match(/^##\s+(\d+)\.\s+(.+?)\s*$/);
+        if (r2)
+            m.set(r2[1], r2[2].trim());
+    }
+    return m;
+}
+/** alpha.59z.42 -- parse `G<N>: Title` lines from docs/doctrine/gates.md.
+ *  Returns slug -> title (e.g. "G2" -> "No minimum brain (LLM) key in vault").
+ *  The scenario fixtures use richer slugs like "G2-vault-min-keys" which
+ *  also resolve here via the normaliseGateSlug step. */
+function parseGateTitles(text) {
+    const m = new Map();
+    for (const line of text.split(/\r?\n/)) {
+        const r = line.match(/^(G\d+):\s+(.+?)\s*$/);
+        if (r)
+            m.set(r[1], r[2].trim());
+    }
+    return m;
+}
+/** Strip the descriptive suffix from gate slugs: "G2-vault-min-keys" -> "G2".
+ *  Non-gate slugs (purely numeric SQ rules) are returned unchanged. */
+function normaliseGateSlug(slug) {
+    const m = slug.match(/^(G\d+)(?:[-_].*)?$/);
+    return m ? m[1] : slug;
+}
+async function loadYaml() {
+    if (_yamlCache)
+        return _yamlCache;
+    const t = await readDoc('SQ_BY_STEP.yaml');
+    if (!t) {
+        _yamlCache = {};
+        return _yamlCache;
+    }
+    _yamlCache = parseYaml(t);
+    return _yamlCache;
+}
+async function loadTitles() {
+    if (_titlesCache)
+        return _titlesCache;
+    const t = await readDoc('SQ.md');
+    const m = t ? parseSqTitles(t) : new Map();
+    /* alpha.59z.42 -- merge gate titles from doctrine/gates.md so
+     *  active_sq_rules entries like "G2-vault-min-keys" resolve to
+     *  the gate description. Gates are part of the same "rule
+     *  enforcement at this step" surface from the brain's POV. */
+    const gates = await readDoc(path.join('doctrine', 'gates.md'));
+    if (gates) {
+        const gateTitles = parseGateTitles(gates);
+        for (const [k, v] of gateTitles.entries())
+            m.set(k, v);
+    }
+    _titlesCache = m;
+    return _titlesCache;
+}
+/** Force-clear caches. Used by tests. */
+export function _clearSqResolverCaches() {
+    _yamlCache = null;
+    _titlesCache = null;
+}
+/** Canonicalise a step descriptor to the YAML key. Accepts:
+ *  - 'step_15_block_dev' (already canonical)
+ *  - 15 (number; we resolve by scanning yaml keys starting with `step_15_`)
+ *  - 'phase_v' (returns null -- not granular enough)
+ */
+function canonicalStepKey(yaml, descriptor) {
+    if (typeof descriptor === 'string' && descriptor.startsWith('step_')) {
+        return descriptor in yaml ? descriptor : null;
+    }
+    if (typeof descriptor === 'number') {
+        const prefix = 'step_' + descriptor + '_';
+        for (const k of Object.keys(yaml)) {
+            if (k.startsWith(prefix))
+                return k;
+        }
+        /* Also try plain "step_<N>" without slug. */
+        return 'step_' + descriptor in yaml ? 'step_' + descriptor : null;
+    }
+    return null;
+}
+/** Return the active SQ rule slugs for a given step, merged with
+ *  the always-active cross-cutting set. Deduped. */
+export async function activeRulesForStep(stepDescriptor) {
+    const yaml = await loadYaml();
+    const cross = yaml['cross_cutting'] || [];
+    if (stepDescriptor === null || stepDescriptor === undefined) {
+        return cross.slice();
+    }
+    const key = canonicalStepKey(yaml, stepDescriptor);
+    const stepRules = key ? (yaml[key] || []) : [];
+    const merged = new Set([...cross, ...stepRules]);
+    return Array.from(merged);
+}
+/** Render a compact "ACTIVE SQ RULES" block for the system prompt.
+ *  Format: `SQ <slug>  <title>` one per line. Returns empty when
+ *  no rules apply (e.g., yaml missing). */
+export async function renderActiveRulesBlock(stepDescriptor) {
+    const slugs = await activeRulesForStep(stepDescriptor);
+    return renderRulesBlockBySlugs(slugs);
+}
+/** Render the ACTIVE SQ RULES block from an explicit slug list.
+ *  Used when the workflow state declares `active_sq_rules` directly
+ *  (alpha.59z.5 F1 -- skip the step inference path). */
+export async function renderRulesBlockBySlugs(slugs) {
+    if (slugs.length === 0)
+        return '';
+    const titles = await loadTitles();
+    const lines = [];
+    lines.push('ACTIVE SQ RULES (subset of docs/SQ.md) -- ENFORCE actively:');
+    for (const slug of slugs) {
+        /* alpha.59z.42 -- accept rich gate slugs like
+         *  "G2-vault-min-keys" + resolve to the base gate description
+         *  from docs/doctrine/gates.md. SQ rules (numeric slugs) pass
+         *  through unchanged. The `[GATE]` marker is appended inline
+         *  so the brain treats it as a hard block while the existing
+         *  "SQ <slug>" prefix stays stable for tests + consumers. */
+        const lookup = normaliseGateSlug(slug);
+        const title = titles.get(lookup) || '(no title found)';
+        const gateMarker = lookup.startsWith('G') ? ' [GATE -- hard block]' : '';
+        lines.push('SQ ' + lookup.padEnd(5) + ' ' + title + gateMarker);
+    }
+    lines.push('');
+    lines.push('Enforcement: these rules are AUTHORITATIVE for this turn.');
+    lines.push('If the user asks to violate one (skip tests, ignore docs,');
+    lines.push('paste secrets, advance past a [GATE], etc), you MUST refuse +');
+    lines.push('cite the rule by its SQ number + explain the cost briefly.');
+    lines.push('Do NOT simply comply -- the user expects you to defend the rules.');
+    return lines.join('\n');
+}
+//# sourceMappingURL=sq_resolver.js.map

package/dist/core/sq_resolver.js.map

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

package/dist/core/truncation_detector.d.ts

@@ -0,0 +1,68 @@
+/**
+ * F104 -- Truncation detector.
+ *
+ * Detects when an LLM response was cut off by the max_tokens cap.
+ * Pablo's insight 2026-06-03: instead of trusting the provider's
+ * stop_reason field (which varies in shape across Anthropic /
+ * OpenAI / Google / xAI / Mistral / DeepSeek / Cohere), compare
+ * the reported output_tokens against the requested max_tokens
+ * with a small safety margin. If output_tokens >= max_tokens -
+ * MARGIN, treat the response as truncated.
+ *
+ * Rationale:
+ *   - Provider-agnostic: every provider reports output_tokens
+ *     (or input_tokens we can derive output from). stop_reason
+ *     names + values differ.
+ *   - Robust: simple arithmetic, no string parsing.
+ *   - Conservative: we use a small margin to catch boundary
+ *     cases (e.g. response landed at 8190 of 8192 -- almost
+ *     certainly truncated even if the model finished a sentence
+ *     by chance).
+ *
+ * ASCII-only.
+ */
+/** Default margin: how close to max_tokens counts as truncation.
+ *  A response within 32 tokens of the cap is treated as truncated.
+ *  Tuned to catch boundary cases without false positives on
+ *  responses that legitimately end near the cap. */
+export declare const TRUNCATION_MARGIN_TOKENS = 32;
+export interface TruncationDetection {
+    /** True if the response is treated as truncated. */
+    truncated: boolean;
+    /** Reason text for diagnostics. Empty if not truncated. */
+    reason: string;
+    /** The output tokens the provider reported. */
+    output_tokens: number;
+    /** The max_tokens limit the caller requested. */
+    max_tokens: number;
+    /** How many tokens away from the cap (max_tokens - output_tokens). */
+    margin: number;
+}
+/** Inspect a response. Returns {truncated: true, ...} when the
+ *  output_tokens are within MARGIN of max_tokens, OR when the
+ *  provider's stop_reason explicitly says max_tokens (as a
+ *  secondary signal -- the arithmetic check is primary).
+ *
+ *  Both args are required. If the caller does not know
+ *  max_tokens (e.g. a streaming response from a provider that
+ *  refused to honour the cap), pass 0 and we return
+ *  {truncated: false} -- we cannot detect without it. */
+export declare function detectTruncation(opts: {
+    output_tokens: number;
+    max_tokens: number;
+    stop_reason?: string;
+    margin?: number;
+}): TruncationDetection;
+/** Helper to format the truncation banner appended to user-visible
+ *  responses. Returns empty string if not truncated.
+ *
+ *  The banner is intentionally short -- it does NOT include the
+ *  full ForgeError block; the renderer wires that separately via
+ *  renderForgeError(E_RESPONSE_TRUNCATED, {...}). This helper is
+ *  for the trailing inline note.
+ *
+ *  alpha.59z.15 -- localised via i18n. The banner text comes from
+ *  `error.response_truncated.banner` in src/i18n/catalogs/*.json
+ *  with {max} and {suggested} substituted in. */
+export declare function truncationBanner(d: TruncationDetection, lang?: import('../i18n/index.js').SupportedLanguage): Promise<string>;
+//# sourceMappingURL=truncation_detector.d.ts.map

package/dist/core/truncation_detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncation_detector.d.ts","sourceRoot":"","sources":["../../src/core/truncation_detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;oDAGoD;AACpD,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAC;IACnB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;yDAQyD;AACzD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,mBAAmB,CA4DtB;AAED;;;;;;;;;;iDAUiD;AACjD,wBAAsB,gBAAgB,CACpC,CAAC,EAAE,mBAAmB,EACtB,IAAI,CAAC,EAAE,OAAO,kBAAkB,EAAE,iBAAiB,GAClD,OAAO,CAAC,MAAM,CAAC,CAQjB"}

package/dist/core/truncation_detector.js

@@ -0,0 +1,115 @@
+/**
+ * F104 -- Truncation detector.
+ *
+ * Detects when an LLM response was cut off by the max_tokens cap.
+ * Pablo's insight 2026-06-03: instead of trusting the provider's
+ * stop_reason field (which varies in shape across Anthropic /
+ * OpenAI / Google / xAI / Mistral / DeepSeek / Cohere), compare
+ * the reported output_tokens against the requested max_tokens
+ * with a small safety margin. If output_tokens >= max_tokens -
+ * MARGIN, treat the response as truncated.
+ *
+ * Rationale:
+ *   - Provider-agnostic: every provider reports output_tokens
+ *     (or input_tokens we can derive output from). stop_reason
+ *     names + values differ.
+ *   - Robust: simple arithmetic, no string parsing.
+ *   - Conservative: we use a small margin to catch boundary
+ *     cases (e.g. response landed at 8190 of 8192 -- almost
+ *     certainly truncated even if the model finished a sentence
+ *     by chance).
+ *
+ * ASCII-only.
+ */
+/** Default margin: how close to max_tokens counts as truncation.
+ *  A response within 32 tokens of the cap is treated as truncated.
+ *  Tuned to catch boundary cases without false positives on
+ *  responses that legitimately end near the cap. */
+export const TRUNCATION_MARGIN_TOKENS = 32;
+/** Inspect a response. Returns {truncated: true, ...} when the
+ *  output_tokens are within MARGIN of max_tokens, OR when the
+ *  provider's stop_reason explicitly says max_tokens (as a
+ *  secondary signal -- the arithmetic check is primary).
+ *
+ *  Both args are required. If the caller does not know
+ *  max_tokens (e.g. a streaming response from a provider that
+ *  refused to honour the cap), pass 0 and we return
+ *  {truncated: false} -- we cannot detect without it. */
+export function detectTruncation(opts) {
+    const output = Math.max(0, Math.floor(opts.output_tokens || 0));
+    const max = Math.max(0, Math.floor(opts.max_tokens || 0));
+    const margin = Math.max(0, opts.margin ?? TRUNCATION_MARGIN_TOKENS);
+    if (max === 0) {
+        /* Unknown cap -- can't decide via arithmetic. Fall back to
+         * the stop_reason signal alone. */
+        if (opts.stop_reason === 'max_tokens' || opts.stop_reason === 'length') {
+            return {
+                truncated: true,
+                reason: 'provider reported stop_reason=' + opts.stop_reason + ' (max_tokens unknown to caller)',
+                output_tokens: output,
+                max_tokens: max,
+                margin: 0,
+            };
+        }
+        return {
+            truncated: false,
+            reason: '',
+            output_tokens: output,
+            max_tokens: max,
+            margin: 0,
+        };
+    }
+    const distance = max - output;
+    if (distance <= margin) {
+        return {
+            truncated: true,
+            reason: 'output_tokens=' + output + ' is within ' + margin + ' of max_tokens=' + max
+                + (opts.stop_reason ? ' (provider stop_reason=' + opts.stop_reason + ')' : ''),
+            output_tokens: output,
+            max_tokens: max,
+            margin: distance,
+        };
+    }
+    /* Secondary signal: even if arithmetic says we have headroom,
+     * trust the provider if it explicitly says it stopped due to
+     * max_tokens (provider may have inflated output_tokens
+     * estimate, or applied a stricter internal cap). */
+    if (opts.stop_reason === 'max_tokens' || opts.stop_reason === 'length') {
+        return {
+            truncated: true,
+            reason: 'provider reported stop_reason=' + opts.stop_reason + ' (arithmetic would have allowed continuation: ' + distance + ' tokens of headroom)',
+            output_tokens: output,
+            max_tokens: max,
+            margin: distance,
+        };
+    }
+    return {
+        truncated: false,
+        reason: '',
+        output_tokens: output,
+        max_tokens: max,
+        margin: distance,
+    };
+}
+/** Helper to format the truncation banner appended to user-visible
+ *  responses. Returns empty string if not truncated.
+ *
+ *  The banner is intentionally short -- it does NOT include the
+ *  full ForgeError block; the renderer wires that separately via
+ *  renderForgeError(E_RESPONSE_TRUNCATED, {...}). This helper is
+ *  for the trailing inline note.
+ *
+ *  alpha.59z.15 -- localised via i18n. The banner text comes from
+ *  `error.response_truncated.banner` in src/i18n/catalogs/*.json
+ *  with {max} and {suggested} substituted in. */
+export async function truncationBanner(d, lang) {
+    if (!d.truncated)
+        return '';
+    const { tForLang } = await import('../i18n/index.js');
+    const text = tForLang(lang ?? 'es', 'error.response_truncated.banner', {
+        max: d.max_tokens,
+        suggested: d.max_tokens * 2,
+    });
+    return '\n\n' + text;
+}
+//# sourceMappingURL=truncation_detector.js.map

package/dist/core/truncation_detector.js.map

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

package/dist/core/turn_classifier.d.ts

@@ -0,0 +1,62 @@
+/**
+ * turn_classifier.ts -- Gemini mini-prompt that decides tier for
+ * a turn the reasoning_gate flagged as ambiguous (alpha.55).
+ *
+ * Why eco-model for the classifier itself: the question
+ * "simple verb invocation or complex reasoning?" is a routing
+ * decision, not a content decision. Gemini Flash Lite handles it
+ * in ~400 ms for fractions of a cent. The verdict gates whether
+ * the EXPENSIVE turn (full LLM call) goes to eco or frontier.
+ *
+ * Fallback path when Gemini is not reachable or the key is
+ * missing: the gate's own (low-confidence) tier suggestion is
+ * returned with a "classifier_unreachable" signal so the cost log
+ * shows what happened. The chat NEVER blocks on classifier
+ * availability.
+ *
+ * Cache: LRU keyed by sha256 of the user text + previous tier.
+ * 50 entries / 5 min TTL. Saves the classifier call on repeated
+ * short prompts ("hola", "ok", "si").
+ *
+ * ASCII-only.
+ */
+export type ClassifierVerdict = 'simple' | 'complex' | 'destructive';
+export interface ClassifierInput {
+    /** The user message. */
+    text: string;
+    /** Tier the gate would have picked when called alone. Used as
+     *  fallback if the classifier fails. */
+    gate_tier: 'eco' | 'frontier';
+    /** Previous tier in the conversation, used for the cache key. */
+    previous_tier?: 'eco' | 'frontier';
+    /** Optional override for the model used (test fixture). */
+    model?: string;
+    /** Optional override for the API key fetch (test fixture). */
+    api_key?: string | null;
+    /** Optional fetch implementation (test fixture). */
+    fetchImpl?: typeof fetch;
+    /** Optional timeout override (ms). Default 2500. */
+    timeoutMs?: number;
+}
+export interface ClassifierResult {
+    /** Tier chosen for the turn. */
+    tier: 'eco' | 'frontier';
+    /** Confidence 0..1. 0.50 when classifier failed and we fell
+     *  back to the gate verdict. */
+    confidence: number;
+    /** Verdict the classifier returned (null when unreachable). */
+    verdict: ClassifierVerdict | null;
+    /** Trail of what happened. Goes to brain_routing.jsonl. */
+    signals: string[];
+    /** True when the call was served from cache. */
+    cached: boolean;
+}
+/** Test hook -- clear cache between specs. */
+export declare function _resetClassifierCache(): void;
+/**
+ * Run the classifier. Never throws -- on any failure, returns
+ * the gate's fallback tier with a "classifier_unreachable"
+ * signal and confidence 0.50.
+ */
+export declare function classifyTurn(input: ClassifierInput): Promise<ClassifierResult>;
+//# sourceMappingURL=turn_classifier.d.ts.map

package/dist/core/turn_classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn_classifier.d.ts","sourceRoot":"","sources":["../../src/core/turn_classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,SAAS,GAAG,aAAa,CAAC;AAErE,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb;4CACwC;IACxC,SAAS,EAAE,KAAK,GAAG,UAAU,CAAC;IAC9B,iEAAiE;IACjE,aAAa,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC;IACnC,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,oDAAoD;IACpD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,gCAAgC;IAChC,IAAI,EAAE,KAAK,GAAG,UAAU,CAAC;IACzB;oCACgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAClC,2DAA2D;IAC3D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,gDAAgD;IAChD,MAAM,EAAE,OAAO,CAAC;CACjB;AA4DD,8CAA8C;AAC9C,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AA6ED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAoEpF"}