/** * @fileoverview CAR String Parser and Generator * * Provides parsing, generation, and validation for Categorical Agent * Registry (CAR) strings. CAR strings follow the format: * * `{registry}.{organization}.{agentClass}:{domains}-L{level}@{version}[#extensions]` * * Example: `a3i.acme-corp.invoice-bot:ABF-L3@1.0.0` * * **CRITICAL DESIGN PRINCIPLE:** * The CAR is an IMMUTABLE identifier (like a certificate or passport number). * Trust is NOT encoded in the CAR - it is computed at RUNTIME based on: * - Attestations (stored separately) * - Behavioral signals * - Deployment context policies * * The optional extensions (section 5+) are mutable and can be defined by * industry or community standards. * * @module @vorionsys/contracts/car/car-string */ import { z } from 'zod'; import { type DomainCode } from './domains.js'; import { CapabilityLevel } from './levels.js'; /** * Regular expression for parsing CAR strings. * * Format: `{registry}.{organization}.{agentClass}:{domains}-L{level}@{version}[#extensions]` * * Groups: * 1. registry - Certifying registry (e.g., 'a3i') * 2. organization - Operating organization (e.g., 'acme-corp') * 3. agentClass - Agent classification (e.g., 'invoice-bot') * 4. domains - Capability domain codes (e.g., 'ABF') * 5. level - Autonomy level (0-7) * 6. version - Semantic version (e.g., '1.0.0') * 7. extensions - Optional comma-separated extensions (e.g., 'gov,audit') * * NOTE: Trust tier is NOT part of the CAR. Trust is computed at runtime * from attestations, behavioral signals, and deployment context. */ export declare const CAR_REGEX: RegExp; /** * Looser regex for partial CAR validation. */ export declare const CAR_PARTIAL_REGEX: RegExp; /** * Legacy regex for parsing old-format CAR strings that include trust tier. * Used for migration/compatibility only. * @deprecated Use CAR_REGEX instead - trust tier should not be in the identifier */ export declare const CAR_LEGACY_REGEX: RegExp; /** @deprecated Use CAR_REGEX instead */ export declare const ACI_REGEX: RegExp; /** @deprecated Use CAR_PARTIAL_REGEX instead */ export declare const ACI_PARTIAL_REGEX: RegExp; /** @deprecated Use CAR_LEGACY_REGEX instead */ export declare const ACI_LEGACY_REGEX: RegExp; /** * Parsed components of a CAR string. * * NOTE: Trust tier is NOT included because the CAR is an immutable identifier. * Trust is computed at runtime from: * - Attestations (external certifications) * - Behavioral signals (runtime observations) * - Deployment context policies */ export interface ParsedCAR { /** Full CAR string */ readonly car: string; /** Certifying registry (e.g., 'a3i') */ readonly registry: string; /** Operating organization */ readonly organization: string; /** Agent classification */ readonly agentClass: string; /** Capability domain codes */ readonly domains: readonly DomainCode[]; /** Domain bitmask for efficient queries */ readonly domainsBitmask: number; /** Autonomy/capability level */ readonly level: CapabilityLevel; /** Semantic version string */ readonly version: string; /** Optional extensions (mutable, industry/community defined) */ readonly extensions: readonly string[]; } /** * @deprecated Use ParsedCAR instead */ export interface ParsedACI extends ParsedCAR { /** @deprecated Use car instead */ readonly carId: string; } /** * Unique identity portion of the CAR (immutable core). * Format: {registry}.{organization}.{agentClass} */ export type CARIdentity = `${string}.${string}.${string}`; /** * @deprecated Use CARIdentity instead */ export type ACIIdentity = CARIdentity; /** * Extracts the identity portion from a parsed CAR. */ export declare function getCARIdentity(parsed: ParsedCAR): CARIdentity; /** * @deprecated Use getCARIdentity instead */ export declare function getACIIdentity(parsed: ParsedCAR): CARIdentity; /** * Zod schema for ParsedCAR validation. */ export declare const parsedCARSchema: z.ZodObject<{ car: z.ZodString; registry: z.ZodString; organization: z.ZodString; agentClass: z.ZodString; domains: z.ZodArray, "many">; domainsBitmask: z.ZodNumber; level: z.ZodNativeEnum; version: z.ZodString; extensions: z.ZodDefault>; }, "strip", z.ZodTypeAny, { version: string; level: CapabilityLevel; registry: string; organization: string; agentClass: string; domains: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[]; domainsBitmask: number; car: string; extensions: string[]; }, { version: string; level: CapabilityLevel; registry: string; organization: string; agentClass: string; domains: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[]; domainsBitmask: number; car: string; extensions?: string[] | undefined; }>; /** @deprecated Use parsedCARSchema instead */ export declare const parsedACISchema: z.ZodObject<{ car: z.ZodString; registry: z.ZodString; organization: z.ZodString; agentClass: z.ZodString; domains: z.ZodArray, "many">; domainsBitmask: z.ZodNumber; level: z.ZodNativeEnum; version: z.ZodString; extensions: z.ZodDefault>; }, "strip", z.ZodTypeAny, { version: string; level: CapabilityLevel; registry: string; organization: string; agentClass: string; domains: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[]; domainsBitmask: number; car: string; extensions: string[]; }, { version: string; level: CapabilityLevel; registry: string; organization: string; agentClass: string; domains: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[]; domainsBitmask: number; car: string; extensions?: string[] | undefined; }>; /** * Error thrown when CAR parsing fails. */ export declare class CARParseError extends Error { /** The invalid CAR string that caused the error */ readonly car: string; /** Error code for programmatic handling */ readonly code: CARParseErrorCode; constructor(message: string, car: string, code?: CARParseErrorCode); } /** * @deprecated Use CARParseError instead */ export declare class ACIParseError extends CARParseError { /** @deprecated Use car instead */ readonly carId: string; constructor(message: string, carId: string, code?: CARParseErrorCode); } /** * Error codes for CAR parse errors. */ export type CARParseErrorCode = 'INVALID_FORMAT' | 'INVALID_REGISTRY' | 'INVALID_ORGANIZATION' | 'INVALID_AGENT_CLASS' | 'INVALID_DOMAINS' | 'NO_DOMAINS' | 'INVALID_LEVEL' | 'INVALID_VERSION' | 'INVALID_EXTENSIONS' | 'LEGACY_FORMAT'; /** @deprecated Use CARParseErrorCode instead */ export type ACIParseErrorCode = CARParseErrorCode; /** * Parses a CAR string into its components. * * @param car - The CAR string to parse * @returns Parsed CAR components * @throws CARParseError if the CAR string is invalid * * @example * ```typescript * const parsed = parseCAR('a3i.acme-corp.invoice-bot:ABF-L3@1.0.0'); * // { * // car: 'a3i.acme-corp.invoice-bot:ABF-L3@1.0.0', * // registry: 'a3i', * // organization: 'acme-corp', * // agentClass: 'invoice-bot', * // domains: ['A', 'B', 'F'], * // domainsBitmask: 0x023, * // level: CapabilityLevel.L3_EXECUTE, * // version: '1.0.0', * // extensions: [] * // } * ``` */ export declare function parseCAR(car: string): ParsedCAR; /** * @deprecated Use parseCAR instead */ export declare function parseACI(carId: string): ParsedCAR & { carId: string; }; /** * Parses a legacy CAR string that includes trust tier. * Returns the parsed CAR (without tier) plus the extracted tier value. * * @deprecated Use parseCAR() - trust should not be in the identifier * @param car - Legacy CAR string with embedded tier * @returns Parsed CAR plus extracted tier */ export declare function parseLegacyCAR(car: string): { parsed: ParsedCAR; legacyTier: number; }; /** * @deprecated Use parseLegacyCAR instead */ export declare function parseLegacyACI(carId: string): { parsed: ParsedCAR & { carId: string; }; legacyTier: number; }; /** * Safely parses a CAR string, returning null on failure. * * @param car - The CAR string to parse * @returns Parsed CAR or null if invalid */ export declare function tryParseCAR(car: string): ParsedCAR | null; /** * @deprecated Use tryParseCAR instead */ export declare function tryParseACI(carId: string): (ParsedCAR & { carId: string; }) | null; /** * Safely parses a CAR string, returning a result object. * * @param car - The CAR string to parse * @returns Result object with success flag and parsed CAR or error */ export declare function safeParseCAR(car: string): { success: true; data: ParsedCAR; } | { success: false; error: CARParseError; }; /** * @deprecated Use safeParseCAR instead */ export declare function safeParseACI(carId: string): { success: true; data: ParsedCAR & { carId: string; }; } | { success: false; error: CARParseError; }; /** * Options for generating a CAR string. * * NOTE: Trust tier is NOT included because CAR is an immutable identifier. * Trust is computed at runtime from attestations and behavioral signals. */ export interface GenerateCAROptions { /** Certifying registry (e.g., 'a3i') */ registry: string; /** Operating organization */ organization: string; /** Agent classification */ agentClass: string; /** Capability domains */ domains: readonly DomainCode[]; /** Autonomy level */ level: CapabilityLevel; /** Semantic version */ version: string; /** Optional extensions (mutable, industry/community defined) */ extensions?: readonly string[]; } /** @deprecated Use GenerateCAROptions instead */ export type GenerateACIOptions = GenerateCAROptions; /** * Generates a CAR string from components. * * @param options - CAR components * @returns Generated CAR string * * @example * ```typescript * const car = generateCAR({ * registry: 'a3i', * organization: 'acme-corp', * agentClass: 'invoice-bot', * domains: ['A', 'B', 'F'], * level: CapabilityLevel.L3_EXECUTE, * version: '1.0.0', * }); * // 'a3i.acme-corp.invoice-bot:ABF-L3@1.0.0' * * // With extensions: * const carWithExt = generateCAR({ * registry: 'a3i', * organization: 'acme-corp', * agentClass: 'invoice-bot', * domains: ['A', 'B', 'F'], * level: CapabilityLevel.L3_EXECUTE, * version: '1.0.0', * extensions: ['gov', 'audit'], * }); * // 'a3i.acme-corp.invoice-bot:ABF-L3@1.0.0#gov,audit' * ``` */ export declare function generateCAR(options: GenerateCAROptions): string; /** * @deprecated Use generateCAR instead */ export declare function generateACI(options: GenerateCAROptions): string; /** * Generates a CAR string from individual parameters. * * @param registry - Certifying registry * @param organization - Operating organization * @param agentClass - Agent classification * @param domains - Capability domains * @param level - Autonomy level * @param version - Semantic version * @param extensions - Optional extensions * @returns Generated CAR string */ export declare function generateCARString(registry: string, organization: string, agentClass: string, domains: readonly DomainCode[], level: CapabilityLevel, version: string, extensions?: readonly string[]): string; /** * @deprecated Use generateCARString instead */ export declare function generateACIString(registry: string, organization: string, agentClass: string, domains: readonly DomainCode[], level: CapabilityLevel, version: string, extensions?: readonly string[]): string; /** * Validation error for CAR strings. */ export interface CARValidationError { /** Error code */ code: string; /** Human-readable message */ message: string; /** Path to the error (if applicable) */ path?: string; } /** @deprecated Use CARValidationError instead */ export type ACIValidationError = CARValidationError; /** * Validation warning for CAR strings. */ export interface CARValidationWarning { /** Warning code */ code: string; /** Human-readable message */ message: string; /** Path to the warning (if applicable) */ path?: string; } /** @deprecated Use CARValidationWarning instead */ export type ACIValidationWarning = CARValidationWarning; /** * Result of CAR validation. */ export interface CARValidationResult { /** Whether the CAR is valid */ valid: boolean; /** Validation errors */ errors: CARValidationError[]; /** Validation warnings */ warnings: CARValidationWarning[]; /** Parsed CAR if valid */ parsed?: ParsedCAR; } /** @deprecated Use CARValidationResult instead */ export type ACIValidationResult = CARValidationResult; /** * Validates a CAR string. * * @param car - The CAR string to validate * @returns Validation result * * @example * ```typescript * const result = validateCAR('a3i.acme-corp.bot:A-L5@1.0.0'); * // { * // valid: true, * // errors: [], * // warnings: [], * // parsed: { ... } * // } * ``` */ export declare function validateCAR(car: string): CARValidationResult; /** * @deprecated Use validateCAR instead */ export declare function validateACI(carId: string): CARValidationResult; /** * Checks if a string is a valid CAR format. * * @param car - String to check * @returns True if the string is a valid CAR */ export declare function isValidCAR(car: string): boolean; /** * @deprecated Use isValidCAR instead */ export declare function isValidACI(carId: string): boolean; /** * Type guard to check if a value is a valid CAR string. * * @param value - Value to check * @returns True if value is a valid CAR string */ export declare function isCARString(value: unknown): value is string; /** * @deprecated Use isCARString instead */ export declare function isACIString(value: unknown): value is string; /** * Updates specific fields in a CAR and returns a new CAR string. * * @param car - Original CAR string * @param updates - Fields to update * @returns New CAR string with updates applied */ export declare function updateCAR(car: string, updates: Partial>): string; /** * @deprecated Use updateCAR instead */ export declare function updateACI(carId: string, updates: Partial>): string; /** * Adds extensions to a CAR string. * * @param car - Original CAR string * @param newExtensions - Extensions to add * @returns New CAR string with extensions added */ export declare function addCARExtensions(car: string, newExtensions: readonly string[]): string; /** * @deprecated Use addCARExtensions instead */ export declare function addACIExtensions(carId: string, newExtensions: readonly string[]): string; /** * Removes extensions from a CAR string. * * @param car - Original CAR string * @param extensionsToRemove - Extensions to remove * @returns New CAR string with extensions removed */ export declare function removeCARExtensions(car: string, extensionsToRemove: readonly string[]): string; /** * @deprecated Use removeCARExtensions instead */ export declare function removeACIExtensions(carId: string, extensionsToRemove: readonly string[]): string; /** * Increments the version in a CAR string. * * @param car - Original CAR string * @param type - Version component to increment ('major' | 'minor' | 'patch') * @returns New CAR string with incremented version */ export declare function incrementCARVersion(car: string, type?: 'major' | 'minor' | 'patch'): string; /** * @deprecated Use incrementCARVersion instead */ export declare function incrementACIVersion(carId: string, type?: 'major' | 'minor' | 'patch'): string; /** * Zod schema for CAR string validation. */ export declare const carStringSchema: z.ZodEffects; /** @deprecated Use carStringSchema instead */ export declare const aciStringSchema: z.ZodEffects; /** * Zod schema for CAR string with parsing transform. */ export declare const carSchema: z.ZodEffects, ParsedCAR, string>; /** @deprecated Use carSchema instead */ export declare const aciSchema: z.ZodEffects, ParsedCAR & { carId: string; }, string>; /** * Zod schema for GenerateCAROptions. */ export declare const generateCAROptionsSchema: z.ZodObject<{ registry: z.ZodString; organization: z.ZodString; agentClass: z.ZodString; domains: z.ZodArray, "many">; level: z.ZodNativeEnum; version: z.ZodString; extensions: z.ZodOptional>; }, "strip", z.ZodTypeAny, { version: string; level: CapabilityLevel; registry: string; organization: string; agentClass: string; domains: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[]; extensions?: string[] | undefined; }, { version: string; level: CapabilityLevel; registry: string; organization: string; agentClass: string; domains: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[]; extensions?: string[] | undefined; }>; /** @deprecated Use generateCAROptionsSchema instead */ export declare const generateACIOptionsSchema: z.ZodObject<{ registry: z.ZodString; organization: z.ZodString; agentClass: z.ZodString; domains: z.ZodArray, "many">; level: z.ZodNativeEnum; version: z.ZodString; extensions: z.ZodOptional>; }, "strip", z.ZodTypeAny, { version: string; level: CapabilityLevel; registry: string; organization: string; agentClass: string; domains: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[]; extensions?: string[] | undefined; }, { version: string; level: CapabilityLevel; registry: string; organization: string; agentClass: string; domains: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[]; extensions?: string[] | undefined; }>; /** * Zod schema for CARValidationError. */ export declare const carValidationErrorSchema: z.ZodObject<{ code: z.ZodString; message: z.ZodString; path: z.ZodOptional; }, "strip", z.ZodTypeAny, { code: string; message: string; path?: string | undefined; }, { code: string; message: string; path?: string | undefined; }>; /** @deprecated Use carValidationErrorSchema instead */ export declare const aciValidationErrorSchema: z.ZodObject<{ code: z.ZodString; message: z.ZodString; path: z.ZodOptional; }, "strip", z.ZodTypeAny, { code: string; message: string; path?: string | undefined; }, { code: string; message: string; path?: string | undefined; }>; /** * Zod schema for CARValidationWarning. */ export declare const carValidationWarningSchema: z.ZodObject<{ code: z.ZodString; message: z.ZodString; path: z.ZodOptional; }, "strip", z.ZodTypeAny, { code: string; message: string; path?: string | undefined; }, { code: string; message: string; path?: string | undefined; }>; /** @deprecated Use carValidationWarningSchema instead */ export declare const aciValidationWarningSchema: z.ZodObject<{ code: z.ZodString; message: z.ZodString; path: z.ZodOptional; }, "strip", z.ZodTypeAny, { code: string; message: string; path?: string | undefined; }, { code: string; message: string; path?: string | undefined; }>; /** * Zod schema for CARValidationResult. */ export declare const carValidationResultSchema: z.ZodObject<{ valid: z.ZodBoolean; errors: z.ZodArray; }, "strip", z.ZodTypeAny, { code: string; message: string; path?: string | undefined; }, { code: string; message: string; path?: string | undefined; }>, "many">; warnings: z.ZodArray; }, "strip", z.ZodTypeAny, { code: string; message: string; path?: string | undefined; }, { code: string; message: string; path?: string | undefined; }>, "many">; parsed: z.ZodOptional, "many">; domainsBitmask: z.ZodNumber; level: z.ZodNativeEnum; version: z.ZodString; extensions: z.ZodDefault>; }, "strip", z.ZodTypeAny, { version: string; level: CapabilityLevel; registry: string; organization: string; agentClass: string; domains: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[]; domainsBitmask: number; car: string; extensions: string[]; }, { version: string; level: CapabilityLevel; registry: string; organization: string; agentClass: string; domains: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[]; domainsBitmask: number; car: string; extensions?: string[] | undefined; }>>; }, "strip", z.ZodTypeAny, { valid: boolean; errors: { code: string; message: string; path?: string | undefined; }[]; warnings: { code: string; message: string; path?: string | undefined; }[]; parsed?: { version: string; level: CapabilityLevel; registry: string; organization: string; agentClass: string; domains: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[]; domainsBitmask: number; car: string; extensions: string[]; } | undefined; }, { valid: boolean; errors: { code: string; message: string; path?: string | undefined; }[]; warnings: { code: string; message: string; path?: string | undefined; }[]; parsed?: { version: string; level: CapabilityLevel; registry: string; organization: string; agentClass: string; domains: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[]; domainsBitmask: number; car: string; extensions?: string[] | undefined; } | undefined; }>; /** @deprecated Use carValidationResultSchema instead */ export declare const aciValidationResultSchema: z.ZodObject<{ valid: z.ZodBoolean; errors: z.ZodArray; }, "strip", z.ZodTypeAny, { code: string; message: string; path?: string | undefined; }, { code: string; message: string; path?: string | undefined; }>, "many">; warnings: z.ZodArray; }, "strip", z.ZodTypeAny, { code: string; message: string; path?: string | undefined; }, { code: string; message: string; path?: string | undefined; }>, "many">; parsed: z.ZodOptional, "many">; domainsBitmask: z.ZodNumber; level: z.ZodNativeEnum; version: z.ZodString; extensions: z.ZodDefault>; }, "strip", z.ZodTypeAny, { version: string; level: CapabilityLevel; registry: string; organization: string; agentClass: string; domains: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[]; domainsBitmask: number; car: string; extensions: string[]; }, { version: string; level: CapabilityLevel; registry: string; organization: string; agentClass: string; domains: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[]; domainsBitmask: number; car: string; extensions?: string[] | undefined; }>>; }, "strip", z.ZodTypeAny, { valid: boolean; errors: { code: string; message: string; path?: string | undefined; }[]; warnings: { code: string; message: string; path?: string | undefined; }[]; parsed?: { version: string; level: CapabilityLevel; registry: string; organization: string; agentClass: string; domains: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[]; domainsBitmask: number; car: string; extensions: string[]; } | undefined; }, { valid: boolean; errors: { code: string; message: string; path?: string | undefined; }[]; warnings: { code: string; message: string; path?: string | undefined; }[]; parsed?: { version: string; level: CapabilityLevel; registry: string; organization: string; agentClass: string; domains: ("A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z")[]; domainsBitmask: number; car: string; extensions?: string[] | undefined; } | undefined; }>;