@anthropic-field/core 0.1.0

package/dist/src/cognitive/runtime/prompt-builder.js

@@ -0,0 +1,216 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Cognitive Prompt Builder
+ * Builds the complete prompt for LLM execution.
+ */
+// =============================================================================
+// Argument Substitution
+// =============================================================================
+/**
+ * Substitute $ARGUMENTS and $N placeholders in text.
+ */
+export function substituteArguments(text, input) {
+    // Get the main argument value
+    const argsValue = String(input['$ARGUMENTS'] ?? input['query'] ?? input['code'] ?? '');
+    // Replace $ARGUMENTS
+    let result = text.replace(/\$ARGUMENTS/g, argsValue);
+    // Replace $ARGUMENTS[N] and $N for indexed access
+    const argsList = argsValue.split(/\s+/);
+    for (let i = 0; i < argsList.length; i++) {
+        result = result.replace(new RegExp(`\\$ARGUMENTS\\[${i}\\]`, 'g'), argsList[i]);
+        result = result.replace(new RegExp(`\\$${i}`, 'g'), argsList[i]);
+    }
+    return result;
+}
+// =============================================================================
+// Constraints Formatting
+// =============================================================================
+/**
+ * Format constraints as YAML-like text for the prompt.
+ */
+export function formatConstraints(module) {
+    const lines = [];
+    // Operational constraints from policies
+    const policies = module.policies;
+    if (policies && Object.keys(policies).length > 0) {
+        lines.push('operational:');
+        if (policies.network === 'deny') {
+            lines.push('  no_external_network: true');
+        }
+        if (policies.filesystem_write === 'deny') {
+            lines.push('  no_file_write: true');
+        }
+        if (policies.side_effects === 'deny') {
+            lines.push('  no_side_effects: true');
+        }
+        if (policies.code_execution === 'deny') {
+            lines.push('  no_code_execution: true');
+        }
+    }
+    // Excludes
+    if (module.excludes && module.excludes.length > 0) {
+        lines.push('excludes:');
+        for (const exclude of module.excludes) {
+            lines.push(`  - ${exclude}`);
+        }
+    }
+    return lines.join('\n');
+}
+// =============================================================================
+// Schema Formatting
+// =============================================================================
+/**
+ * Format JSON schema for prompt inclusion.
+ */
+export function formatSchema(schema, label) {
+    if (!schema || Object.keys(schema).length === 0) {
+        return '';
+    }
+    return `### ${label} Schema\n\`\`\`json\n${JSON.stringify(schema, null, 2)}\n\`\`\``;
+}
+// =============================================================================
+// Envelope Format Instructions
+// =============================================================================
+const ENVELOPE_V22_INSTRUCTIONS = `
+## Response Format (Envelope v2.2)
+
+You MUST wrap your response in the v2.2 envelope format with separate meta and data:
+
+### Success Response
+\`\`\`json
+{
+  "ok": true,
+  "meta": {
+    "confidence": 0.9,
+    "risk": "low",
+    "explain": "Short summary for control plane (≤280 chars)"
+  },
+  "data": {
+    "...your output fields...",
+    "rationale": "Detailed reasoning for audit (no limit)"
+  }
+}
+\`\`\`
+
+### Error Response
+\`\`\`json
+{
+  "ok": false,
+  "meta": {
+    "confidence": 0.0,
+    "risk": "high",
+    "explain": "Error summary (≤280 chars)"
+  },
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable error description"
+  }
+}
+\`\`\`
+
+### Rules
+- meta.explain MUST be ≤280 characters
+- meta.risk MUST be one of: none, low, medium, high
+- meta.confidence MUST be between 0 and 1
+- data.rationale can be longer for detailed reasoning
+- Return ONLY valid JSON
+`;
+const ENVELOPE_V21_INSTRUCTIONS = `
+## Response Format (Envelope)
+
+You MUST wrap your response in the envelope format:
+- Success: { "ok": true, "data": { ...your output... } }
+- Error: { "ok": false, "error": { "code": "ERROR_CODE", "message": "..." } }
+
+Return ONLY valid JSON.
+`;
+const LEGACY_INSTRUCTIONS = `
+## Instructions
+
+Analyze the input and generate output matching the required schema.
+Return ONLY valid JSON. Do not include any text before or after the JSON.
+`;
+/**
+ * Build the complete prompt for the LLM.
+ */
+export function buildPrompt(module, input, options = {}) {
+    const { useEnvelope = true, useV22 = true, includeSchemas = true } = options;
+    // Substitute $ARGUMENTS in prompt
+    const prompt = substituteArguments(module.prompt, input);
+    const parts = [];
+    // Module prompt
+    parts.push(prompt);
+    // Responsibility and excludes
+    if (module.responsibility) {
+        parts.push(`\n## Responsibility\n${module.responsibility}`);
+    }
+    // Constraints
+    const constraints = formatConstraints(module);
+    if (constraints) {
+        parts.push(`\n## Constraints\n${constraints}`);
+    }
+    // Input data
+    parts.push('\n## Input');
+    parts.push('```json');
+    parts.push(JSON.stringify(input, null, 2));
+    parts.push('```');
+    // Schemas (optional)
+    if (includeSchemas) {
+        const inputSchemaText = formatSchema(module.inputSchema, 'Input');
+        const dataSchemaText = formatSchema(module.dataSchema, 'Output');
+        if (inputSchemaText || dataSchemaText) {
+            parts.push('\n## Schemas');
+            if (dataSchemaText) {
+                parts.push(dataSchemaText);
+            }
+        }
+    }
+    // Response format instructions
+    if (useEnvelope) {
+        parts.push(useV22 ? ENVELOPE_V22_INSTRUCTIONS : ENVELOPE_V21_INSTRUCTIONS);
+    }
+    else {
+        parts.push(LEGACY_INSTRUCTIONS);
+    }
+    return parts.join('\n');
+}
+// =============================================================================
+// System Prompt Generation
+// =============================================================================
+/**
+ * Generate a system prompt for the cognitive module.
+ */
+export function buildSystemPrompt(module) {
+    const parts = [];
+    parts.push(`You are a specialized AI module: ${module.name}`);
+    if (module.responsibility) {
+        parts.push(`\nYour responsibility: ${module.responsibility}`);
+    }
+    if (module.excludes && module.excludes.length > 0) {
+        parts.push('\nYou must NOT:');
+        for (const exclude of module.excludes) {
+            parts.push(`- ${exclude}`);
+        }
+    }
+    // Tier-specific instructions
+    if (module.tier) {
+        parts.push(`\nModule tier: ${module.tier}`);
+        switch (module.tier) {
+            case 'exec':
+                parts.push('You must be precise and follow the schema strictly.');
+                break;
+            case 'decision':
+                parts.push('You must provide clear reasoning and confidence scores.');
+                break;
+            case 'exploration':
+                parts.push('You may explore freely but must structure your findings.');
+                break;
+        }
+    }
+    parts.push('\nAlways respond with valid JSON in the specified envelope format.');
+    return parts.join('\n');
+}
+//# sourceMappingURL=prompt-builder.js.map

package/dist/src/cognitive/runtime/prompt-builder.js.map

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

package/dist/src/cognitive/runtime/repair-pass.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Cognitive Repair Pass
+ * Attempts to repair envelope format issues without changing semantics.
+ *
+ * SPEC v2.2 Rules:
+ * - Repair pass MUST NOT invent new enum values
+ * - Only apply lossless normalization (trim whitespace)
+ * - Enum value errors should be treated as validation failures
+ */
+import type { EnvelopeResponse, RiskRule } from '../types.js';
+export interface RepairResult {
+    repaired: EnvelopeResponse;
+    repairs: string[];
+}
+/**
+ * Attempt to repair envelope format issues without changing semantics.
+ *
+ * Repairs (mostly lossless, except explain truncation):
+ * - Missing meta fields (fill with conservative defaults)
+ * - Truncate explain if too long (lossy operation, but required for v2.2 spec)
+ * - Trim whitespace from string fields (lossless)
+ * - Clamp confidence to [0, 1] range (lossy if out of range)
+ *
+ * Does NOT repair:
+ * - Invalid enum values (treated as validation failure)
+ */
+export declare function repairEnvelope(envelope: Record<string, unknown>, riskRule?: RiskRule): RepairResult;
+/**
+ * Repair error envelope format.
+ */
+export declare function repairErrorEnvelope(envelope: Record<string, unknown>): RepairResult;
+/**
+ * Check if meta can be repaired (vs needs full validation failure).
+ */
+export declare function isMetaRepairable(meta: unknown): boolean;
+/**
+ * Full repair pipeline with pre-check.
+ */
+export declare function tryRepair(envelope: Record<string, unknown>, riskRule?: RiskRule): RepairResult | null;

package/dist/src/cognitive/runtime/repair-pass.js

@@ -0,0 +1,170 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Cognitive Repair Pass
+ * Attempts to repair envelope format issues without changing semantics.
+ *
+ * SPEC v2.2 Rules:
+ * - Repair pass MUST NOT invent new enum values
+ * - Only apply lossless normalization (trim whitespace)
+ * - Enum value errors should be treated as validation failures
+ */
+import { aggregateRisk } from './risk-aggregator.js';
+// =============================================================================
+// Constants
+// =============================================================================
+const MAX_EXPLAIN_LENGTH = 280;
+const VALID_RISK_LEVELS = ['none', 'low', 'medium', 'high'];
+/**
+ * Attempt to repair envelope format issues without changing semantics.
+ *
+ * Repairs (mostly lossless, except explain truncation):
+ * - Missing meta fields (fill with conservative defaults)
+ * - Truncate explain if too long (lossy operation, but required for v2.2 spec)
+ * - Trim whitespace from string fields (lossless)
+ * - Clamp confidence to [0, 1] range (lossy if out of range)
+ *
+ * Does NOT repair:
+ * - Invalid enum values (treated as validation failure)
+ */
+export function repairEnvelope(envelope, riskRule = 'max_changes_risk') {
+    const repairs = [];
+    const repaired = { ...envelope };
+    // Ensure meta exists
+    if (!('meta' in repaired) || typeof repaired['meta'] !== 'object' || repaired['meta'] === null) {
+        repaired['meta'] = {};
+        repairs.push('Added missing meta object');
+    }
+    const meta = { ...repaired['meta'] };
+    const data = (repaired['data'] ?? {});
+    // Repair confidence
+    if (!('confidence' in meta)) {
+        // Try to extract from data (v2.1 compatibility)
+        const dataConfidence = data['confidence'];
+        meta['confidence'] = typeof dataConfidence === 'number' ? dataConfidence : 0.5;
+        repairs.push(`Added meta.confidence: ${meta['confidence']}`);
+    }
+    // Ensure confidence is in valid range
+    if (typeof meta['confidence'] === 'number') {
+        const original = meta['confidence'];
+        meta['confidence'] = Math.max(0.0, Math.min(1.0, meta['confidence']));
+        if (original !== meta['confidence']) {
+            repairs.push(`Clamped meta.confidence from ${original} to ${meta['confidence']}`);
+        }
+    }
+    // Repair risk - use configurable aggregation rule
+    if (!('risk' in meta)) {
+        meta['risk'] = aggregateRisk(data, riskRule);
+        repairs.push(`Added meta.risk: ${meta['risk']}`);
+    }
+    // Trim whitespace from risk (lossless), but do NOT invent new values
+    if (typeof meta['risk'] === 'string') {
+        const trimmed = meta['risk'].trim().toLowerCase();
+        if (trimmed !== meta['risk']) {
+            repairs.push(`Trimmed meta.risk whitespace`);
+        }
+        meta['risk'] = trimmed;
+        // If invalid after trim, leave as-is (validation will catch it)
+        // SPEC: "Repair pass MUST NOT invent new enum values"
+    }
+    // Repair explain
+    if (!('explain' in meta)) {
+        // Try to extract from rationale
+        const rationale = data['rationale'];
+        if (typeof rationale === 'string' && rationale.length > 0) {
+            meta['explain'] = rationale.substring(0, MAX_EXPLAIN_LENGTH);
+            repairs.push('Extracted meta.explain from data.rationale');
+        }
+        else {
+            meta['explain'] = 'No explanation provided';
+            repairs.push('Added default meta.explain');
+        }
+    }
+    // Trim whitespace from explain (lossless)
+    if (typeof meta['explain'] === 'string') {
+        const trimmed = meta['explain'].trim();
+        if (trimmed !== meta['explain']) {
+            repairs.push('Trimmed meta.explain whitespace');
+        }
+        meta['explain'] = trimmed;
+    }
+    // Truncate explain if too long
+    if (typeof meta['explain'] === 'string' && meta['explain'].length > MAX_EXPLAIN_LENGTH) {
+        meta['explain'] = meta['explain'].substring(0, MAX_EXPLAIN_LENGTH - 3) + '...';
+        repairs.push(`Truncated meta.explain to ${MAX_EXPLAIN_LENGTH} chars`);
+    }
+    repaired['meta'] = meta;
+    return {
+        repaired: repaired,
+        repairs,
+    };
+}
+/**
+ * Repair error envelope format.
+ */
+export function repairErrorEnvelope(envelope) {
+    const repairs = [];
+    const repaired = { ...envelope };
+    // Ensure meta exists for errors
+    if (!('meta' in repaired) || typeof repaired['meta'] !== 'object' || repaired['meta'] === null) {
+        repaired['meta'] = {};
+        repairs.push('Added missing meta object');
+    }
+    const meta = { ...repaired['meta'] };
+    const error = (repaired['error'] ?? {});
+    // Set default meta for errors
+    if (!('confidence' in meta)) {
+        meta['confidence'] = 0.0;
+        repairs.push('Set meta.confidence to 0.0 for error');
+    }
+    if (!('risk' in meta)) {
+        meta['risk'] = 'high';
+        repairs.push('Set meta.risk to high for error');
+    }
+    if (!('explain' in meta)) {
+        const message = typeof error['message'] === 'string' ? error['message'] : 'An error occurred';
+        meta['explain'] = message.substring(0, MAX_EXPLAIN_LENGTH);
+        repairs.push('Extracted meta.explain from error.message');
+    }
+    repaired['meta'] = meta;
+    return {
+        repaired: repaired,
+        repairs,
+    };
+}
+/**
+ * Check if meta can be repaired (vs needs full validation failure).
+ */
+export function isMetaRepairable(meta) {
+    if (typeof meta !== 'object' || meta === null) {
+        return true; // Can create from scratch
+    }
+    const m = meta;
+    // If risk is present and invalid enum, cannot repair
+    if ('risk' in m) {
+        const risk = m['risk'];
+        if (typeof risk === 'string') {
+            const normalized = risk.trim().toLowerCase();
+            if (!VALID_RISK_LEVELS.includes(normalized)) {
+                return false; // Invalid enum, cannot invent values
+            }
+        }
+    }
+    return true;
+}
+/**
+ * Full repair pipeline with pre-check.
+ */
+export function tryRepair(envelope, riskRule = 'max_changes_risk') {
+    // Check if repairable
+    if (!isMetaRepairable(envelope['meta'])) {
+        return null; // Cannot repair, will fail validation
+    }
+    if (envelope['ok'] === false) {
+        return repairErrorEnvelope(envelope);
+    }
+    return repairEnvelope(envelope, riskRule);
+}
+//# sourceMappingURL=repair-pass.js.map

package/dist/src/cognitive/runtime/repair-pass.js.map

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

package/dist/src/cognitive/runtime/risk-aggregator.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Cognitive Risk Aggregator
+ * Computes aggregated risk level based on module configuration.
+ */
+import type { RiskLevel, RiskRule } from '../types.js';
+/**
+ * Compute max risk from a list of items with risk field.
+ */
+export declare function aggregateRiskFromList(items: Array<Record<string, unknown>>): RiskLevel;
+/**
+ * Compute aggregated risk based on risk_rule.
+ *
+ * Rules:
+ * - max_changes_risk: max(data.changes[*].risk) - default
+ * - max_issues_risk: max(data.issues[*].risk) - for review modules
+ * - explicit: return "medium", module should set risk explicitly
+ */
+export declare function aggregateRisk(data: Record<string, unknown>, riskRule?: RiskRule): RiskLevel;
+/**
+ * Compare two risk levels.
+ * Returns: negative if a < b, 0 if equal, positive if a > b
+ */
+export declare function compareRisk(a: RiskLevel, b: RiskLevel): number;
+/**
+ * Get the higher of two risk levels.
+ */
+export declare function maxRisk(a: RiskLevel, b: RiskLevel): RiskLevel;
+/**
+ * Check if risk level requires human review.
+ */
+export declare function requiresReview(risk: RiskLevel): boolean;
+/**
+ * Check if risk level requires confirmation before execution.
+ */
+export declare function requiresConfirmation(risk: RiskLevel): boolean;

package/dist/src/cognitive/runtime/risk-aggregator.js

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Cognitive Risk Aggregator
+ * Computes aggregated risk level based on module configuration.
+ */
+// =============================================================================
+// Risk Level Mapping
+// =============================================================================
+const RISK_LEVELS = {
+    none: 0,
+    low: 1,
+    medium: 2,
+    high: 3,
+};
+const RISK_NAMES = ['none', 'low', 'medium', 'high'];
+// =============================================================================
+// Risk Aggregation Functions
+// =============================================================================
+/**
+ * Compute max risk from a list of items with risk field.
+ */
+export function aggregateRiskFromList(items) {
+    if (!items || items.length === 0) {
+        return 'medium'; // Default conservative
+    }
+    let maxLevel = 0;
+    for (const item of items) {
+        const risk = item['risk'];
+        const level = RISK_LEVELS[risk ?? 'medium'] ?? 2;
+        maxLevel = Math.max(maxLevel, level);
+    }
+    return RISK_NAMES[maxLevel];
+}
+/**
+ * Compute aggregated risk based on risk_rule.
+ *
+ * Rules:
+ * - max_changes_risk: max(data.changes[*].risk) - default
+ * - max_issues_risk: max(data.issues[*].risk) - for review modules
+ * - explicit: return "medium", module should set risk explicitly
+ */
+export function aggregateRisk(data, riskRule = 'max_changes_risk') {
+    switch (riskRule) {
+        case 'max_changes_risk': {
+            const changes = data['changes'];
+            return aggregateRiskFromList(changes ?? []);
+        }
+        case 'max_issues_risk': {
+            const issues = data['issues'];
+            return aggregateRiskFromList(issues ?? []);
+        }
+        case 'explicit':
+            // Module should override, return default
+            return 'medium';
+        default: {
+            // Fallback to changes
+            const changes = data['changes'];
+            return aggregateRiskFromList(changes ?? []);
+        }
+    }
+}
+/**
+ * Compare two risk levels.
+ * Returns: negative if a < b, 0 if equal, positive if a > b
+ */
+export function compareRisk(a, b) {
+    return RISK_LEVELS[a] - RISK_LEVELS[b];
+}
+/**
+ * Get the higher of two risk levels.
+ */
+export function maxRisk(a, b) {
+    return compareRisk(a, b) >= 0 ? a : b;
+}
+/**
+ * Check if risk level requires human review.
+ */
+export function requiresReview(risk) {
+    return risk === 'high';
+}
+/**
+ * Check if risk level requires confirmation before execution.
+ */
+export function requiresConfirmation(risk) {
+    return risk === 'high' || risk === 'medium';
+}
+//# sourceMappingURL=risk-aggregator.js.map

package/dist/src/cognitive/runtime/risk-aggregator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk-aggregator.js","sourceRoot":"","sources":["../../../../src/cognitive/runtime/risk-aggregator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,gFAAgF;AAChF,qBAAqB;AACrB,gFAAgF;AAEhF,MAAM,WAAW,GAA2B;IAC1C,IAAI,EAAE,CAAC;IACP,GAAG,EAAE,CAAC;IACN,MAAM,EAAE,CAAC;IACT,IAAI,EAAE,CAAC;CACR,CAAC;AAEF,MAAM,UAAU,GAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;AAElE,gFAAgF;AAChF,6BAA6B;AAC7B,gFAAgF;AAEhF;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAqC;IAErC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,QAAQ,CAAC,CAAC,uBAAuB;IAC1C,CAAC;IAED,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAuB,CAAC;QAChD,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC;QACjD,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,IAA6B,EAC7B,WAAqB,kBAAkB;IAEvC,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,kBAAkB,CAAC,CAAC,CAAC;YACxB,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAA+C,CAAC;YAC9E,OAAO,qBAAqB,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;QAC9C,CAAC;QACD,KAAK,iBAAiB,CAAC,CAAC,CAAC;YACvB,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAA+C,CAAC;YAC5E,OAAO,qBAAqB,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;QAC7C,CAAC;QACD,KAAK,UAAU;YACb,yCAAyC;YACzC,OAAO,QAAQ,CAAC;QAClB,OAAO,CAAC,CAAC,CAAC;YACR,sBAAsB;YACtB,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAA+C,CAAC;YAC9E,OAAO,qBAAqB,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,CAAY,EAAE,CAAY;IACpD,OAAO,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;AACzC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,OAAO,CAAC,CAAY,EAAE,CAAY;IAChD,OAAO,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,IAAe;IAC5C,OAAO,IAAI,KAAK,MAAM,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAe;IAClD,OAAO,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,QAAQ,CAAC;AAC9C,CAAC"}