@vorionsys/contracts 0.1.0

package/dist/aci/skills.d.ts

@@ -0,0 +1,314 @@
+/**
+ * @fileoverview ACI 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 @vorion/contracts/aci/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, {
+    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;
+    category: "security" | "development" | "content" | "analysis" | "business";
+    legacyId?: string | undefined;
+}, {
+    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;
+    category: "security" | "development" | "content" | "analysis" | "business";
+    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>;
+//# sourceMappingURL=skills.d.ts.map

package/dist/aci/skills.d.ts.map

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