@vorionsys/platform-core 0.1.0

package/dist/car-extensions/car-string-extensions.js

@@ -0,0 +1,473 @@
+/**
+ * CAR String Extension Utilities
+ *
+ * Provides parsing and manipulation functions for CAR strings with
+ * extension suffixes. Extensions are declared in CAR strings using
+ * the # suffix format.
+ *
+ * @packageDocumentation
+ * @module @vorion/car-extensions/car-string-extensions
+ * @license Apache-2.0
+ *
+ * @example
+ * ```
+ * // CAR string formats:
+ * // Without extensions:
+ * //   a3i.vorion.banquet-advisor:FHC-L3@1.2.0
+ * //
+ * // With single extension:
+ * //   a3i.vorion.banquet-advisor:FHC-L3@1.2.0#gov
+ * //
+ * // With multiple extensions:
+ * //   a3i.vorion.banquet-advisor:FHC-L3@1.2.0#gov,audit,hipaa
+ * ```
+ */
+import { z } from 'zod';
+/**
+ * Zod schema for ParsedExtensions validation
+ */
+export const ParsedExtensionsSchema = z.object({
+    core: z.string().min(1),
+    extensions: z.array(z.string()),
+});
+/**
+ * Regular expression for validating extension ID format
+ * Format: car-ext-{name}-v{major}
+ * Example: car-ext-governance-v1
+ */
+const EXTENSION_ID_REGEX = /^car-ext-[a-z]+-v\d+$/;
+/**
+ * @deprecated Use EXTENSION_ID_REGEX - CAR format still accepted for backwards compatibility
+ */
+const CAR_EXTENSION_ID_REGEX = /^car-ext-[a-z]+-v\d+$/;
+/**
+ * Regular expression for validating shortcode format
+ * Format: 1-10 lowercase letters
+ * Example: gov, audit, hipaa
+ */
+const SHORTCODE_REGEX = /^[a-z]{1,10}$/;
+/**
+ * Regular expression for validating CAR string with optional extensions
+ * Matches: namespace.publisher.name:DOMAINS-L{level}@version[#extensions]
+ * Note: Trust tier is NOT part of CAR - it's computed at runtime
+ */
+const CAR_WITH_EXTENSIONS_REGEX = /^[a-z0-9]+\.[a-z0-9-]+\.[a-z0-9-]+:[A-Z]+-L[0-7]@\d+\.\d+\.\d+(#[a-z]+(,[a-z]+)*)?$/;
+/**
+ * @deprecated Use CAR_WITH_EXTENSIONS_REGEX
+ */
+const ACI_WITH_EXTENSIONS_REGEX = CAR_WITH_EXTENSIONS_REGEX;
+/**
+ * Parse extension suffix from a CAR string
+ *
+ * Extracts the core CAR string and any extension shortcodes from
+ * a CAR string that may include an extension suffix.
+ *
+ * @param car - The CAR string to parse (with or without extensions)
+ * @returns Object containing core CAR string and array of extensions
+ *
+ * @example
+ * ```typescript
+ * // Without extensions
+ * parseExtensions('a3i.vorion.agent:FHC-L3@1.0.0');
+ * // { core: 'a3i.vorion.agent:FHC-L3@1.0.0', extensions: [] }
+ *
+ * // With single extension
+ * parseExtensions('a3i.vorion.agent:FHC-L3@1.0.0#gov');
+ * // { core: 'a3i.vorion.agent:FHC-L3@1.0.0', extensions: ['gov'] }
+ *
+ * // With multiple extensions
+ * parseExtensions('a3i.vorion.agent:FHC-L3@1.0.0#gov,audit,hipaa');
+ * // { core: 'a3i.vorion.agent:FHC-L3@1.0.0', extensions: ['gov', 'audit', 'hipaa'] }
+ * ```
+ */
+export function parseExtensions(car) {
+    const hashIndex = car.indexOf('#');
+    if (hashIndex === -1) {
+        return { core: car, extensions: [] };
+    }
+    const core = car.slice(0, hashIndex);
+    const extSuffix = car.slice(hashIndex + 1);
+    // Split by comma and trim whitespace
+    const extensions = extSuffix
+        .split(',')
+        .map((e) => e.trim())
+        .filter((e) => e.length > 0);
+    return { core, extensions };
+}
+/**
+ * Add an extension shortcode to a CAR string
+ *
+ * If the extension is already present, the string is returned unchanged.
+ * Extensions are appended to the end of the extension list.
+ *
+ * @param car - The CAR string (with or without existing extensions)
+ * @param extension - The extension shortcode to add
+ * @returns The CAR string with the extension added
+ *
+ * @example
+ * ```typescript
+ * // Add to string without extensions
+ * addExtension('a3i.vorion.agent:FHC-L3@1.0.0', 'gov');
+ * // 'a3i.vorion.agent:FHC-L3@1.0.0#gov'
+ *
+ * // Add to string with existing extensions
+ * addExtension('a3i.vorion.agent:FHC-L3@1.0.0#gov', 'audit');
+ * // 'a3i.vorion.agent:FHC-L3@1.0.0#gov,audit'
+ *
+ * // Extension already present
+ * addExtension('a3i.vorion.agent:FHC-L3@1.0.0#gov', 'gov');
+ * // 'a3i.vorion.agent:FHC-L3@1.0.0#gov'
+ * ```
+ */
+export function addExtension(car, extension) {
+    const { core, extensions } = parseExtensions(car);
+    // Don't add if already present
+    if (extensions.includes(extension)) {
+        return car;
+    }
+    extensions.push(extension);
+    return `${core}#${extensions.join(',')}`;
+}
+/**
+ * Add multiple extensions to a CAR string
+ *
+ * Adds all specified extensions that are not already present.
+ * Extensions are appended in the order provided.
+ *
+ * @param car - The CAR string (with or without existing extensions)
+ * @param extensionsToAdd - Array of extension shortcodes to add
+ * @returns The CAR string with all extensions added
+ *
+ * @example
+ * ```typescript
+ * addExtensions('a3i.vorion.agent:FHC-L3@1.0.0', ['gov', 'audit']);
+ * // 'a3i.vorion.agent:FHC-L3@1.0.0#gov,audit'
+ * ```
+ */
+export function addExtensions(car, extensionsToAdd) {
+    let result = car;
+    for (const ext of extensionsToAdd) {
+        result = addExtension(result, ext);
+    }
+    return result;
+}
+/**
+ * Remove an extension shortcode from a CAR string
+ *
+ * If the extension is not present, the string is returned unchanged.
+ * If removing the last extension, the # suffix is also removed.
+ *
+ * @param car - The CAR string with extensions
+ * @param extension - The extension shortcode to remove
+ * @returns The CAR string with the extension removed
+ *
+ * @example
+ * ```typescript
+ * // Remove from multiple extensions
+ * removeExtension('a3i.vorion.agent:FHC-L3@1.0.0#gov,audit', 'gov');
+ * // 'a3i.vorion.agent:FHC-L3@1.0.0#audit'
+ *
+ * // Remove last extension
+ * removeExtension('a3i.vorion.agent:FHC-L3@1.0.0#gov', 'gov');
+ * // 'a3i.vorion.agent:FHC-L3@1.0.0'
+ *
+ * // Extension not present
+ * removeExtension('a3i.vorion.agent:FHC-L3@1.0.0#gov', 'audit');
+ * // 'a3i.vorion.agent:FHC-L3@1.0.0#gov'
+ * ```
+ */
+export function removeExtension(car, extension) {
+    const { core, extensions } = parseExtensions(car);
+    const filtered = extensions.filter((e) => e !== extension);
+    if (filtered.length === 0) {
+        return core;
+    }
+    return `${core}#${filtered.join(',')}`;
+}
+/**
+ * Remove multiple extensions from a CAR string
+ *
+ * @param car - The CAR string with extensions
+ * @param extensionsToRemove - Array of extension shortcodes to remove
+ * @returns The CAR string with all specified extensions removed
+ */
+export function removeExtensions(car, extensionsToRemove) {
+    const { core, extensions } = parseExtensions(car);
+    const filtered = extensions.filter((e) => !extensionsToRemove.includes(e));
+    if (filtered.length === 0) {
+        return core;
+    }
+    return `${core}#${filtered.join(',')}`;
+}
+/**
+ * Check if a CAR string has a specific extension
+ *
+ * @param car - The CAR string to check
+ * @param extension - The extension shortcode to look for
+ * @returns True if the extension is present, false otherwise
+ *
+ * @example
+ * ```typescript
+ * hasExtension('a3i.vorion.agent:FHC-L3@1.0.0#gov,audit', 'gov');
+ * // true
+ *
+ * hasExtension('a3i.vorion.agent:FHC-L3@1.0.0#gov', 'audit');
+ * // false
+ *
+ * hasExtension('a3i.vorion.agent:FHC-L3@1.0.0', 'gov');
+ * // false
+ * ```
+ */
+export function hasExtension(car, extension) {
+    const { extensions } = parseExtensions(car);
+    return extensions.includes(extension);
+}
+/**
+ * Check if a CAR string has all specified extensions
+ *
+ * @param car - The CAR string to check
+ * @param requiredExtensions - Array of extension shortcodes required
+ * @returns True if all extensions are present, false otherwise
+ */
+export function hasAllExtensions(car, requiredExtensions) {
+    const { extensions } = parseExtensions(car);
+    return requiredExtensions.every((ext) => extensions.includes(ext));
+}
+/**
+ * Check if a CAR string has any of the specified extensions
+ *
+ * @param car - The CAR string to check
+ * @param extensionsToCheck - Array of extension shortcodes to check
+ * @returns True if any extension is present, false otherwise
+ */
+export function hasAnyExtension(car, extensionsToCheck) {
+    const { extensions } = parseExtensions(car);
+    return extensionsToCheck.some((ext) => extensions.includes(ext));
+}
+/**
+ * Validate extension ID format
+ *
+ * Extension IDs must follow the format: car-ext-{name}-v{major}
+ * Where {name} is lowercase letters and {major} is a positive integer.
+ * Also accepts legacy car-ext-{name}-v{major} format for backwards compatibility.
+ *
+ * @param id - The extension ID to validate
+ * @returns True if the ID is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidExtensionId('car-ext-governance-v1');  // true
+ * isValidExtensionId('car-ext-healthcare-v2'); // true
+ * isValidExtensionId('car-ext-governance-v1'); // true (backwards compatibility)
+ * isValidExtensionId('car-ext-CAPS-v1');       // false (uppercase)
+ * isValidExtensionId('my-extension');          // false (wrong format)
+ * isValidExtensionId('car-ext-foo');           // false (missing version)
+ * ```
+ */
+export function isValidExtensionId(id) {
+    return EXTENSION_ID_REGEX.test(id) || CAR_EXTENSION_ID_REGEX.test(id);
+}
+/**
+ * Validate extension shortcode format
+ *
+ * Shortcodes must be 1-10 lowercase letters only.
+ *
+ * @param shortcode - The shortcode to validate
+ * @returns True if the shortcode is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidShortcode('gov');     // true
+ * isValidShortcode('hipaa');   // true
+ * isValidShortcode('audit');   // true
+ * isValidShortcode('GOV');     // false (uppercase)
+ * isValidShortcode('gov1');    // false (contains number)
+ * isValidShortcode('');        // false (empty)
+ * isValidShortcode('verylongcode'); // false (too long)
+ * ```
+ */
+export function isValidShortcode(shortcode) {
+    return SHORTCODE_REGEX.test(shortcode);
+}
+/**
+ * Validate a CAR string with optional extensions
+ *
+ * Validates that the CAR string follows the expected format including
+ * any extension suffix.
+ *
+ * @param car - The CAR string to validate
+ * @returns True if the CAR string is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidCARWithExtensions('a3i.vorion.agent:FHC-L3@1.0.0');           // true
+ * isValidCARWithExtensions('a3i.vorion.agent:FHC-L3@1.0.0#gov');       // true
+ * isValidCARWithExtensions('a3i.vorion.agent:FHC-L3@1.0.0#gov,audit'); // true
+ * isValidCARWithExtensions('invalid-car-string');                      // false
+ * ```
+ */
+export function isValidCARWithExtensions(car) {
+    return CAR_WITH_EXTENSIONS_REGEX.test(car);
+}
+/**
+ * @deprecated Use isValidCARWithExtensions instead
+ */
+export const isValidACIWithExtensions = isValidCARWithExtensions;
+/**
+ * Get the extension count for a CAR string
+ *
+ * @param car - The CAR string to check
+ * @returns Number of extensions in the CAR string
+ */
+export function getExtensionCount(car) {
+    const { extensions } = parseExtensions(car);
+    return extensions.length;
+}
+/**
+ * Replace all extensions in a CAR string
+ *
+ * Removes any existing extensions and adds the new ones.
+ *
+ * @param car - The CAR string (with or without extensions)
+ * @param newExtensions - Array of new extension shortcodes
+ * @returns CAR string with only the new extensions
+ *
+ * @example
+ * ```typescript
+ * replaceExtensions('a3i.vorion.agent:FHC-L3@1.0.0#gov', ['audit', 'hipaa']);
+ * // 'a3i.vorion.agent:FHC-L3@1.0.0#audit,hipaa'
+ *
+ * replaceExtensions('a3i.vorion.agent:FHC-L3@1.0.0#gov', []);
+ * // 'a3i.vorion.agent:FHC-L3@1.0.0'
+ * ```
+ */
+export function replaceExtensions(car, newExtensions) {
+    const { core } = parseExtensions(car);
+    if (newExtensions.length === 0) {
+        return core;
+    }
+    // Remove duplicates while preserving order
+    const unique = Array.from(new Set(newExtensions));
+    return `${core}#${unique.join(',')}`;
+}
+/**
+ * Sort extensions in a CAR string alphabetically
+ *
+ * @param car - The CAR string with extensions
+ * @returns CAR string with extensions sorted alphabetically
+ */
+export function sortExtensions(car) {
+    const { core, extensions } = parseExtensions(car);
+    if (extensions.length === 0) {
+        return core;
+    }
+    const sorted = [...extensions].sort();
+    return `${core}#${sorted.join(',')}`;
+}
+/**
+ * Compare two CAR strings for extension equality
+ *
+ * Checks if two CAR strings have the same extensions (regardless of order).
+ *
+ * @param car1 - First CAR string
+ * @param car2 - Second CAR string
+ * @returns True if both have the same extensions
+ */
+export function haveEqualExtensions(car1, car2) {
+    const ext1 = parseExtensions(car1).extensions.sort();
+    const ext2 = parseExtensions(car2).extensions.sort();
+    if (ext1.length !== ext2.length) {
+        return false;
+    }
+    return ext1.every((e, i) => e === ext2[i]);
+}
+/**
+ * Extract the core CAR string without extensions
+ *
+ * @param car - The CAR string (with or without extensions)
+ * @returns The core CAR string
+ */
+export function getCoreCar(car) {
+    return parseExtensions(car).core;
+}
+/**
+ * @deprecated Use getCoreCar instead
+ */
+export const getCoreCAR = getCoreCar;
+/**
+ * @deprecated Use getCoreCar instead
+ */
+export const getCoreACI = getCoreCar;
+/**
+ * Build a CAR string from core and extensions
+ *
+ * @param core - The core CAR string
+ * @param extensions - Array of extension shortcodes
+ * @returns Complete CAR string with extensions
+ */
+export function buildCAR(core, extensions) {
+    if (extensions.length === 0) {
+        return core;
+    }
+    // Remove duplicates while preserving order
+    const unique = Array.from(new Set(extensions));
+    return `${core}#${unique.join(',')}`;
+}
+/**
+ * @deprecated Use buildCAR instead
+ */
+export const buildACI = buildCAR;
+/**
+ * Parse extension ID to extract name and version
+ *
+ * @param extensionId - The extension ID (e.g., 'car-ext-governance-v1' or 'car-ext-governance-v1')
+ * @returns Object with name and version, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * parseExtensionId('car-ext-governance-v1');
+ * // { name: 'governance', version: 1 }
+ *
+ * parseExtensionId('car-ext-governance-v1');
+ * // { name: 'governance', version: 1 }
+ *
+ * parseExtensionId('invalid');
+ * // null
+ * ```
+ */
+export function parseExtensionId(extensionId) {
+    // Try CAR format first
+    const carMatch = extensionId.match(/^car-ext-([a-z]+)-v(\d+)$/);
+    if (carMatch) {
+        return {
+            name: carMatch[1],
+            version: parseInt(carMatch[2], 10),
+        };
+    }
+    // Try legacy ACI format for backwards compatibility
+    const legacyMatch = extensionId.match(/^aci-ext-([a-z]+)-v(\d+)$/);
+    if (legacyMatch) {
+        return {
+            name: legacyMatch[1],
+            version: parseInt(legacyMatch[2], 10),
+        };
+    }
+    return null;
+}
+/**
+ * Build an extension ID from name and version
+ *
+ * @param name - Extension name (lowercase letters)
+ * @param version - Major version number
+ * @returns Extension ID in format car-ext-{name}-v{version}
+ *
+ * @example
+ * ```typescript
+ * buildExtensionId('governance', 1);
+ * // 'car-ext-governance-v1'
+ * ```
+ */
+export function buildExtensionId(name, version) {
+    return `car-ext-${name.toLowerCase()}-v${version}`;
+}
+//# sourceMappingURL=car-string-extensions.js.map

package/dist/car-extensions/car-string-extensions.js.map

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

package/dist/car-extensions/executor.d.ts

@@ -0,0 +1,208 @@
+/**
+ * CAR Extension Executor
+ *
+ * Executes extension hooks in order with proper timeout handling,
+ * error management, and result aggregation. This is the core engine
+ * that drives the Layer 4 Runtime Assurance functionality.
+ *
+ * @packageDocumentation
+ * @module @vorion/car-extensions/executor
+ * @license Apache-2.0
+ */
+import type { ExtensionRegistry } from './registry.js';
+import { type AgentIdentity, type CapabilityRequest, type CapabilityGrant, type ActionRequest, type ActionRecord, type BehaviorMetrics, type AnomalyReport, type RevocationEvent, type TrustAdjustment, type PolicyContext, type AggregatedPreCheckResult, type AggregatedPreActionResult, type AggregatedFailureResponse, type AggregatedBehaviorResult, type AggregatedMetricsReport, type AggregatedAnomalyResponse, type AggregatedTrustResult, type AggregatedPolicyDecision, type ExtensionServiceConfig } from './types.js';
+/**
+ * Extension Hook Executor
+ *
+ * Executes extension hooks with:
+ * - Timeout enforcement per hook type
+ * - Error isolation between extensions
+ * - Result aggregation according to protocol rules
+ * - Logging and observability
+ *
+ * @example
+ * ```typescript
+ * const executor = new ExtensionExecutor(registry, {
+ *   defaultTimeout: 1000,
+ *   failFast: false,
+ *   logExecution: true,
+ * });
+ *
+ * const result = await executor.executeCapabilityPreCheck(
+ *   ['car-ext-governance-v1', 'car-ext-audit-v1'],
+ *   agent,
+ *   request
+ * );
+ * ```
+ */
+export declare class ExtensionExecutor {
+    private registry;
+    private config;
+    /**
+     * Create a new executor
+     *
+     * @param registry - The extension registry to use
+     * @param config - Optional configuration
+     */
+    constructor(registry: ExtensionRegistry, config?: ExtensionServiceConfig);
+    /**
+     * Execute capability pre-check hooks
+     *
+     * All extensions must return allow=true for the request to be allowed.
+     * Constraints from all extensions are combined.
+     *
+     * @param extensionIds - Extension IDs to execute
+     * @param agent - Agent identity
+     * @param request - Capability request
+     * @returns Aggregated result from all extensions
+     */
+    executeCapabilityPreCheck(extensionIds: string[], agent: AgentIdentity, request: CapabilityRequest): Promise<AggregatedPreCheckResult>;
+    /**
+     * Execute capability post-grant hooks
+     *
+     * Each extension can modify the grant (e.g., add constraints).
+     * Modifications are applied in extension order.
+     *
+     * @param extensionIds - Extension IDs to execute
+     * @param agent - Agent identity
+     * @param grant - Capability grant to modify
+     * @returns Modified capability grant
+     */
+    executeCapabilityPostGrant(extensionIds: string[], agent: AgentIdentity, grant: CapabilityGrant): Promise<CapabilityGrant>;
+    /**
+     * Execute pre-action hooks
+     *
+     * All extensions must return proceed=true for the action to proceed.
+     * Modifications and approval requirements are combined.
+     *
+     * @param extensionIds - Extension IDs to execute
+     * @param agent - Agent identity
+     * @param action - Action request
+     * @returns Aggregated result from all extensions
+     */
+    executeActionPreAction(extensionIds: string[], agent: AgentIdentity, action: ActionRequest): Promise<AggregatedPreActionResult>;
+    /**
+     * Execute post-action hooks
+     *
+     * Called after action execution for logging/audit purposes.
+     * Errors are logged but do not affect the action result.
+     *
+     * @param extensionIds - Extension IDs to execute
+     * @param agent - Agent identity
+     * @param action - Action record
+     */
+    executeActionPostAction(extensionIds: string[], agent: AgentIdentity, action: ActionRecord): Promise<void>;
+    /**
+     * Execute failure handler hooks
+     *
+     * Determines retry behavior and fallback actions.
+     * Takes the most permissive retry suggestion and first fallback.
+     *
+     * @param extensionIds - Extension IDs to execute
+     * @param agent - Agent identity
+     * @param action - Failed action record
+     * @param error - Error that occurred
+     * @returns Aggregated failure response
+     */
+    executeActionOnFailure(extensionIds: string[], agent: AgentIdentity, action: ActionRecord, error: Error): Promise<AggregatedFailureResponse>;
+    /**
+     * Execute behavior verification hooks
+     *
+     * Returns the most severe recommendation and whether any extension
+     * found behavior out of bounds.
+     *
+     * @param extensionIds - Extension IDs to execute
+     * @param agent - Agent identity
+     * @param metrics - Behavior metrics to verify
+     * @returns Aggregated verification result
+     */
+    executeVerifyBehavior(extensionIds: string[], agent: AgentIdentity, metrics: BehaviorMetrics): Promise<AggregatedBehaviorResult>;
+    /**
+     * Execute metrics collection hooks
+     *
+     * Collects metrics from all extensions and aggregates health status.
+     *
+     * @param extensionIds - Extension IDs to execute
+     * @param agent - Agent identity
+     * @returns Aggregated metrics report
+     */
+    executeCollectMetrics(extensionIds: string[], agent: AgentIdentity): Promise<AggregatedMetricsReport>;
+    /**
+     * Execute anomaly handler hooks
+     *
+     * Returns the most severe action taken and aggregates notifications.
+     *
+     * @param extensionIds - Extension IDs to execute
+     * @param agent - Agent identity
+     * @param anomaly - Anomaly report
+     * @returns Aggregated anomaly response
+     */
+    executeOnAnomaly(extensionIds: string[], agent: AgentIdentity, anomaly: AnomalyReport): Promise<AggregatedAnomalyResponse>;
+    /**
+     * Execute revocation handler hooks
+     *
+     * Notifies all extensions of a revocation event.
+     * Errors are logged but do not stop propagation.
+     *
+     * @param extensionIds - Extension IDs to execute
+     * @param revocation - Revocation event
+     */
+    executeOnRevocation(extensionIds: string[], revocation: RevocationEvent): Promise<void>;
+    /**
+     * Execute trust adjustment hooks
+     *
+     * Applies trust adjustments from all extensions sequentially.
+     *
+     * @param extensionIds - Extension IDs to execute
+     * @param agent - Agent identity
+     * @param adjustment - Trust adjustment request
+     * @returns Aggregated trust result
+     */
+    executeAdjustTrust(extensionIds: string[], agent: AgentIdentity, adjustment: TrustAdjustment): Promise<AggregatedTrustResult>;
+    /**
+     * Execute policy evaluation hooks
+     *
+     * Evaluates policies across all extensions and aggregates decisions.
+     * Deny wins over require_approval, which wins over allow.
+     *
+     * @param extensionIds - Extension IDs to execute
+     * @param context - Policy context
+     * @returns Aggregated policy decision
+     */
+    evaluatePolicy(extensionIds: string[], context: PolicyContext): Promise<AggregatedPolicyDecision>;
+    /**
+     * Execute a hook with timeout enforcement
+     *
+     * @param fn - The hook function to execute
+     * @param hookType - Type of hook for timeout lookup
+     * @param extensionId - Extension ID for logging
+     * @returns Hook result
+     * @throws TimeoutError if hook exceeds timeout
+     */
+    private executeWithTimeout;
+    /**
+     * Log a hook execution error
+     *
+     * @param hookType - Type of hook that failed
+     * @param extensionId - Extension that failed
+     * @param error - Error that occurred
+     */
+    private logHookError;
+}
+/**
+ * Create a new extension executor
+ *
+ * @param registry - Extension registry to use
+ * @param config - Optional configuration
+ * @returns New executor instance
+ *
+ * @example
+ * ```typescript
+ * const executor = createExtensionExecutor(registry, {
+ *   failFast: true,
+ *   logExecution: true,
+ * });
+ * ```
+ */
+export declare function createExtensionExecutor(registry: ExtensionRegistry, config?: ExtensionServiceConfig): ExtensionExecutor;
+//# sourceMappingURL=executor.d.ts.map

package/dist/car-extensions/executor.d.ts.map

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