/**
 * @fileoverview CAR Skill Codes and Bitmask Operations
 *
 * Defines the skill codes used for fine-grained capability matching,
 * with bitmask encoding for efficient queries and skill matching.
 *
 * Skills represent specific capabilities within domains. While domains
 * define broad capability areas (A-I, S), skills provide granular
 * specialization within those areas.
 *
 * @module @vorionsys/contracts/car/skills
 */
import { z } from 'zod';
/**
 * Skill codes representing specific agent capabilities.
 *
 * Skills are organized into categories:
 *
 * **Content & Generation:**
 * - TG: Text Generation - General text creation and composition
 * - CW: Content Writing - Blog posts, articles, marketing copy
 * - CR: Creative Writing - Fiction, storytelling, creative content
 * - TD: Technical Documentation - Docs, guides, specifications
 * - TR: Translation - Language translation services
 * - SM: Summarization - Content condensation and extraction
 *
 * **Analysis & Research:**
 * - DA: Data Analysis - Statistical analysis, data processing
 * - RS: Research - Information gathering and synthesis
 * - QA: Question Answering - Q&A, knowledge retrieval
 *
 * **Development & Technical:**
 * - CA: Code Assistance - Programming help, debugging
 * - DV: Development - Software development tasks
 * - RV: Review - Code review, content review
 * - WS: Web Search - Internet search and retrieval
 * - FO: File Operations - File manipulation, I/O
 * - AI: API Integration - External API interactions
 *
 * **Business & Operations:**
 * - PL: Planning - Task planning, scheduling
 * - CM: Communication - Messaging, notifications
 * - CS: Customer Support - Customer service interactions
 * - AU: Automation - Workflow automation
 *
 * **Security & Governance:**
 * - SC: Security - Security-related operations
 * - GV: Governance - Policy and compliance
 */
export type SkillCode = 'TG' | 'CW' | 'CR' | 'TD' | 'TR' | 'SM' | 'DA' | 'RS' | 'QA' | 'CA' | 'DV' | 'RV' | 'WS' | 'FO' | 'AI' | 'PL' | 'CM' | 'CS' | 'AU' | 'SC' | 'GV';
/**
 * Array of all valid skill codes.
 */
export declare const SKILL_CODES: readonly SkillCode[];
/**
 * Zod schema for SkillCode validation.
 */
export declare const skillCodeSchema: z.ZodEnum<["TG", "CW", "CR", "TD", "TR", "SM", "DA", "RS", "QA", "CA", "DV", "RV", "WS", "FO", "AI", "PL", "CM", "CS", "AU", "SC", "GV"]>;
/**
 * Skill category for grouping related skills.
 */
export type SkillCategory = 'content' | 'analysis' | 'development' | 'business' | 'security';
/**
 * Complete definition for a skill.
 */
export interface SkillDefinition {
    /** Two-character skill code */
    readonly code: SkillCode;
    /** Human-readable skill name */
    readonly name: string;
    /** Bitmask value for efficient queries (power of 2) */
    readonly bit: number;
    /** Description of the skill's scope */
    readonly description: string;
    /** Category grouping */
    readonly category: SkillCategory;
    /** Legacy string identifier for backward compatibility */
    readonly legacyId?: string;
}
/**
 * Skill definitions with their bitmask values.
 *
 * Each skill has a unique bitmask value (power of 2) for efficient
 * storage and querying of skill combinations.
 *
 * Using 32-bit integers, we can support up to 32 skills (21 currently defined).
 */
export declare const SKILL_DEFINITIONS: Readonly<Record<SkillCode, SkillDefinition>>;
/**
 * Human-readable skill names indexed by code.
 */
export declare const SKILL_NAMES: Readonly<Record<SkillCode, string>>;
/**
 * Bitmask value representing all skills combined.
 */
export declare const ALL_SKILLS_BITMASK: number;
/**
 * Skills grouped by category.
 */
export declare const SKILLS_BY_CATEGORY: Readonly<Record<SkillCategory, readonly SkillCode[]>>;
/**
 * Map legacy string identifiers to skill codes.
 */
export declare const LEGACY_ID_TO_SKILL: Readonly<Record<string, SkillCode>>;
/**
 * Converts a legacy skill ID to a skill code.
 *
 * @param legacyId - Legacy string identifier
 * @returns Skill code or undefined if not found
 */
export declare function legacyIdToSkillCode(legacyId: string): SkillCode | undefined;
/**
 * Converts an array of legacy skill IDs to skill codes.
 *
 * @param legacyIds - Array of legacy string identifiers
 * @returns Array of skill codes (unrecognized IDs are filtered out)
 */
export declare function legacyIdsToSkillCodes(legacyIds: readonly string[]): SkillCode[];
/**
 * Encodes an array of skill codes into a bitmask.
 *
 * @param skills - Array of skill codes to encode
 * @returns Bitmask integer representing the skills
 *
 * @example
 * ```typescript
 * encodeSkills(['TG', 'CA']);     // 0x201 (513)
 * encodeSkills(['DA', 'RS']);     // 0x0C0 (192)
 * encodeSkills([]);               // 0
 * ```
 */
export declare function encodeSkills(skills: readonly SkillCode[]): number;
/**
 * Decodes a bitmask into an array of skill codes.
 *
 * @param bitmask - Bitmask integer to decode
 * @returns Array of skill codes present in the bitmask
 *
 * @example
 * ```typescript
 * decodeSkills(0x201);  // ['TG', 'CA']
 * decodeSkills(0x0C0);  // ['DA', 'RS']
 * decodeSkills(0);      // []
 * ```
 */
export declare function decodeSkills(bitmask: number): SkillCode[];
/**
 * Parses a skill string (e.g., "TG,CA,DA") into an array of codes.
 *
 * @param skillString - Comma-separated skill codes
 * @returns Array of valid skill codes
 *
 * @example
 * ```typescript
 * parseSkillString('TG,CA,DA');  // ['TG', 'CA', 'DA']
 * parseSkillString('TGCADA');    // ['TG', 'CA', 'DA']
 * parseSkillString('');          // []
 * ```
 */
export declare function parseSkillString(skillString: string): SkillCode[];
/**
 * Formats an array of skill codes into a sorted string.
 *
 * @param skills - Array of skill codes
 * @returns Sorted, deduplicated comma-separated string
 *
 * @example
 * ```typescript
 * formatSkillString(['DA', 'TG', 'CA']);  // 'CA,DA,TG'
 * formatSkillString(['TG', 'TG']);        // 'TG'
 * ```
 */
export declare function formatSkillString(skills: readonly SkillCode[]): string;
/**
 * Checks if a skill bitmask contains all required skills.
 *
 * @param agentSkills - Agent's skill bitmask
 * @param requiredSkills - Required skills bitmask
 * @returns True if agent has all required skills
 *
 * @example
 * ```typescript
 * const agentMask = encodeSkills(['TG', 'CA', 'DA']);
 * const required = encodeSkills(['TG', 'CA']);
 * hasSkills(agentMask, required);  // true
 * ```
 */
export declare function hasSkills(agentSkills: number, requiredSkills: number): boolean;
/**
 * Checks if an agent satisfies skill requirements.
 *
 * @param agentSkills - Agent's skill codes
 * @param requiredSkills - Required skill codes
 * @returns True if agent has all required skills
 */
export declare function satisfiesSkillRequirements(agentSkills: readonly SkillCode[], requiredSkills: readonly SkillCode[]): boolean;
/**
 * Returns the intersection of two skill sets.
 *
 * @param skills1 - First skill set
 * @param skills2 - Second skill set
 * @returns Skills present in both sets
 */
export declare function intersectSkills(skills1: readonly SkillCode[], skills2: readonly SkillCode[]): SkillCode[];
/**
 * Returns the union of two skill sets.
 *
 * @param skills1 - First skill set
 * @param skills2 - Second skill set
 * @returns All skills from both sets
 */
export declare function unionSkills(skills1: readonly SkillCode[], skills2: readonly SkillCode[]): SkillCode[];
/**
 * Returns skills in the first set but not in the second.
 *
 * @param skills1 - First skill set
 * @param skills2 - Second skill set
 * @returns Skills unique to the first set
 */
export declare function differenceSkills(skills1: readonly SkillCode[], skills2: readonly SkillCode[]): SkillCode[];
/**
 * Gets the complete definition for a skill code.
 *
 * @param code - Skill code
 * @returns Skill definition or undefined if not found
 */
export declare function getSkillDefinition(code: SkillCode): SkillDefinition;
/**
 * Gets the human-readable name for a skill code.
 *
 * @param code - Skill code
 * @returns Skill name
 */
export declare function getSkillName(code: SkillCode): string;
/**
 * Gets the bitmask value for a skill code.
 *
 * @param code - Skill code
 * @returns Bitmask value
 */
export declare function getSkillBit(code: SkillCode): number;
/**
 * Gets the category for a skill code.
 *
 * @param code - Skill code
 * @returns Skill category
 */
export declare function getSkillCategory(code: SkillCode): SkillCategory;
/**
 * Gets all skills in a category.
 *
 * @param category - Skill category
 * @returns Array of skill codes in that category
 */
export declare function getSkillsInCategory(category: SkillCategory): readonly SkillCode[];
/**
 * Counts the number of skills in a bitmask.
 *
 * @param bitmask - Skill bitmask
 * @returns Number of skills
 */
export declare function countSkills(bitmask: number): number;
/**
 * Type guard to check if a value is a valid skill code.
 *
 * @param value - Value to check
 * @returns True if value is a valid SkillCode
 */
export declare function isSkillCode(value: unknown): value is SkillCode;
/**
 * Type guard to check if an array contains only valid skill codes.
 *
 * @param values - Array to check
 * @returns True if all values are valid SkillCodes
 */
export declare function isSkillCodeArray(values: unknown): values is SkillCode[];
/**
 * Zod schema for SkillDefinition validation.
 */
export declare const skillDefinitionSchema: z.ZodObject<{
    code: z.ZodEnum<["TG", "CW", "CR", "TD", "TR", "SM", "DA", "RS", "QA", "CA", "DV", "RV", "WS", "FO", "AI", "PL", "CM", "CS", "AU", "SC", "GV"]>;
    name: z.ZodString;
    bit: z.ZodNumber;
    description: z.ZodString;
    category: z.ZodEnum<["content", "analysis", "development", "business", "security"]>;
    legacyId: z.ZodOptional<z.ZodString>;
}, "strip", z.ZodTypeAny, {
    category: "security" | "development" | "content" | "analysis" | "business";
    name: string;
    code: "TG" | "CW" | "CR" | "TD" | "TR" | "SM" | "DA" | "RS" | "QA" | "CA" | "DV" | "RV" | "WS" | "FO" | "AI" | "PL" | "CM" | "CS" | "AU" | "SC" | "GV";
    description: string;
    bit: number;
    legacyId?: string | undefined;
}, {
    category: "security" | "development" | "content" | "analysis" | "business";
    name: string;
    code: "TG" | "CW" | "CR" | "TD" | "TR" | "SM" | "DA" | "RS" | "QA" | "CA" | "DV" | "RV" | "WS" | "FO" | "AI" | "PL" | "CM" | "CS" | "AU" | "SC" | "GV";
    description: string;
    bit: number;
    legacyId?: string | undefined;
}>;
/**
 * Zod schema for skill code array validation.
 */
export declare const skillCodeArraySchema: z.ZodArray<z.ZodEnum<["TG", "CW", "CR", "TD", "TR", "SM", "DA", "RS", "QA", "CA", "DV", "RV", "WS", "FO", "AI", "PL", "CM", "CS", "AU", "SC", "GV"]>, "many">;
/**
 * Zod schema for skill bitmask validation (21 bits max).
 */
export declare const skillBitmaskSchema: z.ZodNumber;
/**
 * Zod schema for skill string validation (comma-separated codes).
 */
export declare const skillStringSchema: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, SkillCode[], string>;