dual-brain 0.2.30 → 0.3.1

package/dist/src/governance.js

@@ -0,0 +1,261 @@
+// governance.ts — Model tier enforcement + multi-model collaboration
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+export const MODEL_TIERS = Object.freeze({
+    1: {
+        label: 'lightweight',
+        models: ['claude-haiku-4-5-20251001', 'haiku', 'gpt-4o-mini', 'o4-mini'],
+        autoApprove: true,
+    },
+    2: {
+        label: 'standard',
+        models: ['claude-sonnet-4-6', 'sonnet', 'gpt-4o', 'gpt-4.1'],
+        autoApprove: true,
+    },
+    3: {
+        label: 'heavy',
+        models: ['claude-opus-4-6', 'claude-opus-4-7', 'opus', 'o3'],
+        autoApprove: false, // requires consent check per profile
+    },
+});
+// Reverse lookup: model ID → tier number
+export function getModelTier(modelId) {
+    if (!modelId)
+        return 2; // default to standard
+    const normalized = String(modelId).toLowerCase();
+    for (const [tier, def] of Object.entries(MODEL_TIERS)) {
+        if (def.models.some(m => normalized.includes(m)))
+            return Number(tier);
+    }
+    return 2; // unknown models default to standard
+}
+export function scoreTask(detection) {
+    const scores = {
+        complexity: 0,
+        risk: 0,
+        creativity: 0,
+        precision: 0,
+        contextVolume: 0,
+    };
+    // Complexity from file count / scope
+    const fileCount = detection?.files?.length || detection?.scope?.fileCount || 0;
+    if (fileCount >= 6)
+        scores.complexity = 3;
+    else if (fileCount >= 3)
+        scores.complexity = 2;
+    else if (fileCount >= 1)
+        scores.complexity = 1;
+    // Risk from explicit risk field or keywords
+    const risk = detection?.risk || detection?.riskLevel || 'low';
+    const riskMap = { low: 0, medium: 1, high: 2, critical: 3 };
+    scores.risk = riskMap[risk] ?? 0;
+    // Boost risk for security/auth/billing keywords
+    const text = (detection?.objective || detection?.intent || '').toLowerCase();
+    if (/\b(auth|security|credential|secret|billing|payment|migration|delete|drop)\b/.test(text)) {
+        scores.risk = Math.max(scores.risk, 2);
+    }
+    // Creativity from intent type
+    const intent = (detection?.intent || detection?.type || '').toLowerCase();
+    if (/\b(architect|design|brainstorm|explore|research)\b/.test(intent))
+        scores.creativity = 2;
+    else if (/\b(refactor|plan|decide)\b/.test(intent))
+        scores.creativity = 1;
+    // Precision — one-shot tasks need higher precision
+    if (/\b(security|deploy|publish|migration)\b/.test(text))
+        scores.precision = 2;
+    else if (/\b(implement|build|create)\b/.test(text))
+        scores.precision = 1;
+    // Context volume
+    const contextSize = detection?.contextTokens || detection?.estimatedContext || 0;
+    if (contextSize > 200000)
+        scores.contextVolume = 3;
+    else if (contextSize > 50000)
+        scores.contextVolume = 2;
+    else if (contextSize > 10000)
+        scores.contextVolume = 1;
+    return scores;
+}
+export function computeRequiredTier(scores) {
+    const total = Object.values(scores).reduce((a, b) => a + b, 0);
+    if (total <= 2)
+        return 1;
+    if (total <= 6)
+        return 2;
+    return 3;
+}
+const GOVERNANCE_PERMISSIONS = {
+    'auto': { 1: 'auto', 2: 'auto', 3: 'ask' },
+    'balanced': { 1: 'auto', 2: 'auto', 3: 'ask' },
+    'cost-saver': { 1: 'auto', 2: 'auto', 3: 'deny' },
+    'quality-first': { 1: 'auto', 2: 'auto', 3: 'auto' },
+};
+// Pricing per million tokens (input/output) for cost estimation
+const MODEL_PRICING = {
+    'haiku': { input: 1.00, output: 5.00 },
+    'sonnet': { input: 3.00, output: 15.00 },
+    'opus': { input: 5.00, output: 25.00 },
+    'gpt-4o-mini': { input: 0.15, output: 0.60 },
+    'gpt-4o': { input: 2.50, output: 10.00 },
+    'gpt-4.1': { input: 2.00, output: 8.00 },
+    'o3': { input: 2.00, output: 8.00 },
+    'o4-mini': { input: 1.10, output: 4.40 },
+};
+function estimateCost(modelId, estimatedTokens = 8000) {
+    const normalized = String(modelId).toLowerCase();
+    let pricing = MODEL_PRICING['sonnet']; // default
+    for (const [key, p] of Object.entries(MODEL_PRICING)) {
+        if (normalized.includes(key)) {
+            pricing = p;
+            break;
+        }
+    }
+    // Assume 20% input, 80% output for agent tasks
+    const inputTokens = estimatedTokens * 0.2;
+    const outputTokens = estimatedTokens * 0.8;
+    return (inputTokens * pricing.input + outputTokens * pricing.output) / 1_000_000;
+}
+export function assessGovernance(model, detection, profile) {
+    const tier = getModelTier(model);
+    const scores = scoreTask(detection);
+    const requiredTier = computeRequiredTier(scores);
+    const workStyle = profile?.workStyle || profile?.name || 'auto';
+    const permissions = GOVERNANCE_PERMISSIONS[workStyle] || GOVERNANCE_PERMISSIONS['auto'];
+    const permission = permissions[tier] || 'ask';
+    const estimatedCost = estimateCost(model);
+    return {
+        requestedTier: tier,
+        requiredTier,
+        overProvisioned: tier > requiredTier,
+        underProvisioned: tier < requiredTier,
+        permission,
+        estimatedCost,
+        scores,
+        justification: buildJustification(scores, tier, requiredTier),
+    };
+}
+function buildJustification(scores, requestedTier, requiredTier) {
+    const parts = [];
+    if (scores.risk >= 2)
+        parts.push('high-risk');
+    if (scores.complexity >= 2)
+        parts.push('complex');
+    if (scores.creativity >= 2)
+        parts.push('creative/architectural');
+    if (scores.contextVolume >= 2)
+        parts.push('large-context');
+    if (requestedTier > requiredTier)
+        parts.push('over-provisioned');
+    if (requestedTier < requiredTier)
+        parts.push('under-provisioned');
+    return parts.join(', ') || 'standard task';
+}
+export function shouldCollaborate(detection, governance, profile) {
+    // Never collaborate on tier-1 tasks
+    if (governance.requiredTier <= 1)
+        return { collaborate: false };
+    // Never collaborate in cost-saver mode unless explicitly requested
+    const workStyle = profile?.workStyle || profile?.name || 'auto';
+    if (workStyle === 'cost-saver')
+        return { collaborate: false };
+    // Check collaboration triggers (need ANY two)
+    const triggers = [];
+    const text = (detection?.objective || detection?.intent || '').toLowerCase();
+    if (/\b(auth|security|credential|billing|migration)\b/.test(text))
+        triggers.push('irreversibility');
+    if (detection?.ambiguity === 'high' || /\b(should we|how to|best approach|tradeoff)\b/.test(text))
+        triggers.push('ambiguity');
+    if (detection?.novelty === 'high' || /\b(new|first time|never done|greenfield)\b/.test(text))
+        triggers.push('novelty');
+    if ((detection?.files?.length || 0) >= 4 && /\b(security|performance|ux)\b/.test(text))
+        triggers.push('cross-domain');
+    if (governance.requestedTier >= 3 && detection?.confidence != null && detection.confidence < 0.8)
+        triggers.push('low-confidence');
+    const shouldDo = triggers.length >= 2;
+    return {
+        collaborate: shouldDo,
+        triggers,
+        pattern: shouldDo ? selectPattern(triggers, detection) : null,
+        estimatedOverhead: shouldDo ? estimateCost('gpt-4.1') : 0,
+    };
+}
+function selectPattern(triggers, detection) {
+    const text = (detection?.objective || detection?.intent || '').toLowerCase();
+    // Security → adversarial review
+    if (triggers.includes('irreversibility') && /\b(auth|security|credential)\b/.test(text)) {
+        return 'adversarial-review';
+    }
+    // Architecture/greenfield → second opinion
+    if (triggers.includes('novelty') || triggers.includes('ambiguity')) {
+        return 'second-opinion';
+    }
+    // Default
+    return 'second-opinion';
+}
+// ─── Governance State (Session Budget Tracking) ──────────────────────────────
+const STATE_FILE = '.dualbrain/governance-state.json';
+const SESSION_GAP_MS = 30 * 60 * 1000; // 30 min gap = new session
+export function loadGovernanceState(cwd) {
+    const statePath = join(cwd, STATE_FILE);
+    try {
+        const raw = JSON.parse(readFileSync(statePath, 'utf8'));
+        // Check if session is stale
+        const lastDispatch = raw.dispatches?.[raw.dispatches.length - 1];
+        if (lastDispatch && (Date.now() - Date.parse(lastDispatch.ts)) > SESSION_GAP_MS) {
+            return freshState();
+        }
+        return raw;
+    }
+    catch {
+        return freshState();
+    }
+}
+function freshState() {
+    return {
+        sessionStartedAt: new Date().toISOString(),
+        dispatches: [],
+        totalEstimatedCost: 0,
+        tierCounts: { 1: 0, 2: 0, 3: 0 },
+    };
+}
+export function recordDispatch(cwd, tier, model, estimatedCost, approved = true) {
+    const state = loadGovernanceState(cwd);
+    state.dispatches.push({
+        tier,
+        model: String(model),
+        estimatedCost,
+        approved,
+        ts: new Date().toISOString(),
+    });
+    state.totalEstimatedCost += estimatedCost;
+    state.tierCounts[tier] = (state.tierCounts[tier] || 0) + 1;
+    const dir = join(cwd, '.dualbrain');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(cwd, STATE_FILE), JSON.stringify(state, null, 2) + '\n');
+    return state;
+}
+export function checkBudget(cwd, orchestratorConfig) {
+    const state = loadGovernanceState(cwd);
+    const sessionLimit = orchestratorConfig?.budgets?.session_limit_usd || 10;
+    const remaining = sessionLimit - state.totalEstimatedCost;
+    return {
+        spent: state.totalEstimatedCost,
+        remaining,
+        limit: sessionLimit,
+        warning: remaining < sessionLimit * 0.2,
+        blocked: remaining <= 0,
+        tierCounts: state.tierCounts,
+    };
+}
+// ─── Format for User Display ─────────────────────────────────────────────────
+export function formatGovernancePrompt(governance, collaboration) {
+    const tierLabel = MODEL_TIERS[governance.requestedTier]?.label || 'unknown';
+    const lines = [];
+    lines.push(`[governance] Task requires ${tierLabel} model (tier ${governance.requestedTier}, ~$${governance.estimatedCost.toFixed(2)})`);
+    if (governance.justification)
+        lines.push(`  Reason: ${governance.justification}`);
+    if (collaboration?.collaborate) {
+        lines.push(`  + ${collaboration.pattern} with secondary model (+$${(collaboration.estimatedOverhead || 0).toFixed(2)})`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=governance.js.map

package/dist/src/governance.js.map

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

package/dist/src/handoff.d.ts

@@ -0,0 +1,11 @@
+import type { HandoffStage, HandoffContract } from './types.js';
+interface HandoffSchema {
+    required: string[];
+    optional: string[];
+}
+export declare const HANDOFF_TYPES: Record<string, HandoffSchema>;
+export declare function createHandoff(fromStage: HandoffStage, toStage: HandoffStage, data: Record<string, unknown>, runId: string, cwd?: string): HandoffContract | null;
+export declare function consumeHandoff(runId: string, fromStage: HandoffStage, toStage: HandoffStage, cwd?: string): HandoffContract | null;
+export declare function buildHandoffContext(handoff: HandoffContract | null, targetRole: string): string;
+export declare function cleanupHandoffs(runId: string, cwd?: string): void;
+export {};

package/dist/src/handoff.js

@@ -0,0 +1,90 @@
+// handoff.ts — Typed handoffs between pipeline stages
+import { writeFileSync, readFileSync, existsSync, mkdirSync, renameSync, unlinkSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+export const HANDOFF_TYPES = {
+    'think-to-work': { required: ['objective', 'files', 'criteria'], optional: ['context', 'confidence'] },
+    'work-to-review': { required: ['filesChanged', 'objective'], optional: ['diff', 'criteria', 'testsRun'] },
+    'review-to-head': { required: ['pass'], optional: ['findings', 'recommendation', 'severity'] },
+};
+const hDir = (cwd) => join(cwd || process.cwd(), '.dualbrain', 'handoffs');
+const hPath = (id, f, t, cwd) => join(hDir(cwd), `${id}_${f}_${t}.json`);
+function validate(from, to, data) {
+    const schema = HANDOFF_TYPES[`${from}-to-${to}`];
+    if (!schema)
+        return;
+    for (const f of schema.required) {
+        if (!(f in data))
+            process.stderr.write(`[handoff] warn: missing required field '${f}' in ${from}-to-${to}\n`);
+    }
+}
+export function createHandoff(fromStage, toStage, data, runId, cwd) {
+    try {
+        validate(fromStage, toStage, data);
+        const safeRunId = String(runId).replace(/[^a-z0-9_-]/gi, '_').slice(0, 50);
+        const dir = hDir(cwd);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const record = { fromStage, toStage, runId: safeRunId, createdAt: new Date().toISOString(), data: data };
+        const dest = hPath(safeRunId, fromStage, toStage, cwd);
+        const tmp = dest + '.tmp';
+        writeFileSync(tmp, JSON.stringify(record, null, 2), 'utf8');
+        try {
+            renameSync(tmp, dest);
+        }
+        catch {
+            writeFileSync(dest, JSON.stringify(record, null, 2), 'utf8');
+        }
+        return record;
+    }
+    catch {
+        return null;
+    }
+}
+export function consumeHandoff(runId, fromStage, toStage, cwd) {
+    try {
+        const safeRunId = String(runId).replace(/[^a-z0-9_-]/gi, '_').slice(0, 50);
+        const p = hPath(safeRunId, fromStage, toStage, cwd);
+        if (!existsSync(p))
+            return null;
+        const record = JSON.parse(readFileSync(p, 'utf8'));
+        try {
+            unlinkSync(p);
+        }
+        catch { /* best-effort */ }
+        return record;
+    }
+    catch {
+        return null;
+    }
+}
+export function buildHandoffContext(handoff, targetRole) {
+    if (!handoff?.data)
+        return '';
+    const d = handoff.data;
+    const lines = (...parts) => parts.filter(Boolean).join('\n');
+    const list = (v) => Array.isArray(v) ? v.join(', ') : (v ?? '');
+    const items = (v) => Array.isArray(v) ? v.map(x => `  - ${x}`).join('\n') : (v ?? '');
+    if (targetRole === 'worker' && handoff.fromStage === 'thinker')
+        return lines('## Handoff from Think Stage', `**Objective:** ${d.objective ?? '(none)'}`, `**Files in scope:** ${list(d.files) || 'unspecified'}`, d.criteria ? `**Acceptance criteria:**\n${items(d.criteria)}` : '', d.context ? `**Context:** ${d.context}` : '', d.confidence != null ? `**Thinker confidence:** ${d.confidence}` : '');
+    if (targetRole === 'reviewer' && handoff.fromStage === 'worker')
+        return lines('## Handoff from Work Stage', `**Objective:** ${d.objective ?? '(none)'}`, `**Files changed:** ${list(d.filesChanged) || 'unknown'}`, d.criteria ? `**Original criteria:** ${Array.isArray(d.criteria) ? d.criteria.join('; ') : d.criteria}` : '', d.testsRun ? `**Tests run:** ${d.testsRun}` : '', d.diff ? `**Diff summary:**\n\`\`\`\n${d.diff.slice(0, 1200)}\n\`\`\`` : '');
+    if (targetRole === 'head' && handoff.fromStage === 'reviewer')
+        return lines(`## Review Result: ${d.pass ? 'PASS' : 'FAIL'}`, d.findings ? `**Findings:**\n${items(d.findings)}` : '', d.recommendation ? `**Recommendation:** ${d.recommendation}` : '', d.severity ? `**Severity:** ${d.severity}` : '');
+    return JSON.stringify(handoff.data, null, 2);
+}
+export function cleanupHandoffs(runId, cwd) {
+    try {
+        const dir = hDir(cwd);
+        if (!existsSync(dir))
+            return;
+        for (const name of readdirSync(dir)) {
+            if (name.startsWith(`${runId}_`))
+                try {
+                    unlinkSync(join(dir, name));
+                }
+                catch { /* best-effort */ }
+        }
+    }
+    catch { /* non-throwing */ }
+}
+//# sourceMappingURL=handoff.js.map

package/dist/src/handoff.js.map

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

package/dist/src/head-protocol.d.ts

@@ -0,0 +1,76 @@
+export interface DispatchPlan {
+    strategy: string;
+    id: string;
+    expectedParallel: number;
+    waveSize: number;
+    subtasks?: string[];
+    reason: string;
+}
+export interface DeliberationArtifact {
+    timestamp: number;
+    createdAt: number;
+    message: string;
+    action: unknown;
+    result: unknown;
+    shouldAskUser: boolean;
+    confidence: unknown;
+    obligations: unknown[];
+    surfaceNoticings: unknown[];
+    dispatchPlan: DispatchPlan | null;
+    depth: string;
+    rationale: string;
+    situation: {
+        taskShape: unknown;
+        urgency: unknown;
+        scope: unknown;
+    };
+}
+interface ProcessTurnResult {
+    action: {
+        type: string;
+        mode?: string;
+    };
+    result: {
+        confidence?: {
+            score?: number;
+        } | null;
+        surfaceNoticings?: unknown[];
+        depth?: string;
+    };
+    shouldAskUser: boolean;
+    obligations?: unknown[];
+    depth: string;
+    rationale: string;
+    situation?: {
+        taskShape?: {
+            scope?: string;
+        } | null;
+        urgency?: string;
+        material?: {
+            touchedFiles?: string[];
+        };
+    };
+}
+interface DispatchContext {
+    subtasks?: Array<string | {
+        name?: string;
+        description?: string;
+    }>;
+    situation?: unknown;
+    result?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Write the deliberation artifact after running HEAD's cognitive pipeline.
+ * This is the contract between HEAD's thinking and the deliberation-gate hook.
+ */
+export declare function writeDeliberation(userMessage: string, context?: DispatchContext): ProcessTurnResult;
+/**
+ * Read the current deliberation artifact.
+ */
+export declare function readDeliberation(): DeliberationArtifact | null;
+/**
+ * Check if the current deliberation is fresh (within maxAgeMs).
+ */
+export declare function isDeliberationFresh(maxAgeMs?: number): boolean;
+export {};

package/dist/src/head-protocol.js

@@ -0,0 +1,109 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { processTurn, loadState } from './head.js';
+const DUALBRAIN = join(process.cwd(), '.dualbrain');
+const DELIBERATION_FILE = join(DUALBRAIN, 'deliberation.json');
+/**
+ * Write the deliberation artifact after running HEAD's cognitive pipeline.
+ * This is the contract between HEAD's thinking and the deliberation-gate hook.
+ */
+export function writeDeliberation(userMessage, context = {}) {
+    const state = loadState();
+    const result = processTurn(state, userMessage, context);
+    // Determine if there are multiple independent sub-tasks that could be parallelized
+    const dispatchPlan = _deriveDispatchPlan(result, context);
+    // Build the artifact
+    const artifact = {
+        timestamp: Date.now(),
+        createdAt: Date.now(),
+        message: userMessage.slice(0, 500),
+        // Core deliberation fields
+        action: result.action,
+        result: result.result,
+        shouldAskUser: result.shouldAskUser,
+        confidence: result.result?.confidence || null,
+        // Obligations and noticings
+        obligations: result.obligations || [],
+        surfaceNoticings: result.result?.surfaceNoticings || [],
+        // Dispatch plan (parallel-wave support)
+        dispatchPlan,
+        // Metadata
+        depth: result.depth,
+        rationale: result.rationale,
+        situation: {
+            taskShape: result.situation?.taskShape || null,
+            urgency: result.situation?.urgency || null,
+            scope: result.situation?.taskShape?.scope || null,
+        },
+    };
+    // Write atomically
+    mkdirSync(DUALBRAIN, { recursive: true });
+    const tmpFile = DELIBERATION_FILE + '.tmp.' + process.pid;
+    writeFileSync(tmpFile, JSON.stringify(artifact, null, 2));
+    renameSync(tmpFile, DELIBERATION_FILE);
+    return result;
+}
+/**
+ * Read the current deliberation artifact.
+ */
+export function readDeliberation() {
+    try {
+        if (!existsSync(DELIBERATION_FILE))
+            return null;
+        return JSON.parse(readFileSync(DELIBERATION_FILE, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if the current deliberation is fresh (within maxAgeMs).
+ */
+export function isDeliberationFresh(maxAgeMs = 60_000) {
+    const delib = readDeliberation();
+    if (!delib)
+        return false;
+    const timestamp = delib.timestamp || delib.createdAt || 0;
+    return (Date.now() - timestamp) <= maxAgeMs;
+}
+// ── Internal helpers ─────────────────────────────────────────────────────────
+/**
+ * Derive a dispatch plan when the situation has multiple independent sub-tasks.
+ * Returns null if parallel dispatch is not applicable.
+ */
+function _deriveDispatchPlan(result, context) {
+    const situation = result.situation;
+    if (!situation)
+        return null;
+    // Only generate a parallel plan for multi-file, non-trivial work
+    const scope = situation.taskShape?.scope;
+    const actionType = result.action?.type;
+    if (scope !== 'large' && scope !== 'medium')
+        return null;
+    if (actionType !== 'dispatch' && actionType !== 'proceed')
+        return null;
+    // Check for independent sub-tasks from context
+    const subtasks = context.subtasks || [];
+    if (subtasks.length < 2) {
+        // Heuristic: large scope with multiple files could be parallel
+        const fileCount = situation.material?.touchedFiles?.length || 0;
+        if (fileCount < 3)
+            return null;
+        return {
+            strategy: 'parallel-wave',
+            id: Date.now().toString(36),
+            expectedParallel: Math.min(fileCount, 5),
+            waveSize: Math.min(fileCount, 5),
+            reason: `${fileCount} independent files detected`,
+        };
+    }
+    return {
+        strategy: 'parallel-wave',
+        id: Date.now().toString(36),
+        expectedParallel: subtasks.length,
+        waveSize: subtasks.length,
+        subtasks: subtasks.map(t => typeof t === 'string' ? t : t.name || t.description || ''),
+        reason: `${subtasks.length} independent sub-tasks identified`,
+    };
+}
+//# sourceMappingURL=head-protocol.js.map

package/dist/src/head-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"head-protocol.js","sourceRoot":"","sources":["../../src/head-protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACzF,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEnD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,YAAY,CAAC,CAAC;AACpD,MAAM,iBAAiB,GAAG,IAAI,CAAC,SAAS,EAAE,mBAAmB,CAAC,CAAC;AA0D/D;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAmB,EAAE,UAA2B,EAAE;IAClF,MAAM,KAAK,GAAG,SAAS,EAAE,CAAC;IAC1B,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAsB,CAAC;IAE7E,mFAAmF;IACnF,MAAM,YAAY,GAAG,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE1D,qBAAqB;IACrB,MAAM,QAAQ,GAAyB;QACrC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;QACrB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;QACrB,OAAO,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;QAElC,2BAA2B;QAC3B,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,IAAI,IAAI;QAE7C,4BAA4B;QAC5B,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,EAAE;QACrC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,IAAI,EAAE;QAEvD,wCAAwC;QACxC,YAAY;QAEZ,WAAW;QACX,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,SAAS,EAAE;YACT,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,SAAS,IAAI,IAAI;YAC9C,OAAO,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,IAAI,IAAI;YAC1C,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,IAAI,IAAI;SAClD;KACF,CAAC;IAEF,mBAAmB;IACnB,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAG,iBAAiB,GAAG,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC;IAC1D,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1D,UAAU,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;IAEvC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC9B,IAAI,CAAC;QACH,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC;YAAE,OAAO,IAAI,CAAC;QAChD,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAyB,CAAC;IACrF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAQ,GAAG,MAAM;IACnD,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;IACjC,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,SAAS,IAAI,CAAC,CAAC;IAC1D,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,IAAI,QAAQ,CAAC;AAC9C,CAAC;AAED,gFAAgF;AAEhF;;;GAGG;AACH,SAAS,mBAAmB,CAAC,MAAyB,EAAE,OAAwB;IAC9E,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;IACnC,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAE5B,iEAAiE;IACjE,MAAM,KAAK,GAAG,SAAS,CAAC,SAAS,EAAE,KAAK,CAAC;IACzC,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC;IAEvC,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzD,IAAI,UAAU,KAAK,UAAU,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAEvE,+CAA+C;IAC/C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;IACxC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,+DAA+D;QAC/D,MAAM,SAAS,GAAG,SAAS,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC,CAAC;QAChE,IAAI,SAAS,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAE/B,OAAO;YACL,QAAQ,EAAE,eAAe;YACzB,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3B,gBAAgB,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;YACxC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;YAChC,MAAM,EAAE,GAAG,SAAS,6BAA6B;SAClD,CAAC;IACJ,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,eAAe;QACzB,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3B,gBAAgB,EAAE,QAAQ,CAAC,MAAM;QACjC,QAAQ,EAAE,QAAQ,CAAC,MAAM;QACzB,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC;QACtF,MAAM,EAAE,GAAG,QAAQ,CAAC,MAAM,mCAAmC;KAC9D,CAAC;AACJ,CAAC"}