agentic-orchestrator 0.1.25 → 0.1.26

package/dist/apps/control-plane/application/services/performance-analytics-service.js

@@ -34,11 +34,73 @@ function computeAggregates(outcomes) {
     }
     return aggregates;
 }
+/**
+ * Manages performance analytics and outcome tracking.
+ *
+ * ## Responsibilities
+ * - Record feature outcomes (status, retries, duration, cost)
+ * - Aggregate metrics by provider/model
+ * - Calculate success rates and averages
+ * - Provide analytics for dashboard
+ *
+ * ## Dependencies
+ * Depends on {@link PerformanceAnalyticsServicePort} for:
+ * - Analytics file path resolution
+ * - Timestamp utilities
+ *
+ * ## Key Methods
+ * - `recordOutcome()` - record feature outcome
+ * - `getAnalytics()` - retrieve aggregated metrics
+ * - `getProviderStats()` - get metrics by provider/model
+ *
+ * ## Error Conditions
+ * - FILE_NOT_FOUND - analytics file does not exist
+ *
+ * @example
+ * ```typescript
+ * const perfService = new PerformanceAnalyticsService(port);
+ * await perfService.recordOutcome({
+ *   feature_id: 'my_feature',
+ *   status: 'merged',
+ *   provider: 'claude',
+ *   model: 'claude-3-5-sonnet-20241022',
+ *   retries: 2,
+ *   duration_ms: 300000,
+ *   cost_usd: 1.50
+ * });
+ * const analytics = await perfService.getAnalytics();
+ * ```
+ *
+ * ## Metrics Tracked
+ * - Success rate by provider/model
+ * - Average cost per feature
+ * - Average duration per phase
+ * - Retry counts and reasons
+ */
 export class PerformanceAnalyticsService {
     port;
     constructor(port) {
         this.port = port;
     }
+    /**
+     * Records feature outcome for analytics.
+     *
+     * @param outcome - outcome data (status, retries, duration, cost, provider, model)
+     * @returns Updated analytics snapshot
+     *
+     * @example
+     * ```typescript
+     * await perfService.recordOutcome({
+     *   feature_id: 'my_feature',
+     *   status: 'merged',
+     *   provider: 'claude',
+     *   model: 'claude-3-5-sonnet-20241022',
+     *   retries: 2,
+     *   duration_ms: 300000,
+     *   cost_usd: 1.50
+     * });
+     * ```
+     */
     async recordOutcome(outcome) {
         const filePath = this.port.analyticsPath();
         await ensureDir(path.dirname(filePath));
@@ -49,9 +111,33 @@ export class PerformanceAnalyticsService {
         await atomicWriteJson(filePath, current);
         return current;
     }
+    /**
+     * Retrieves aggregated performance analytics.
+     *
+     * @returns Analytics snapshot with provider/model metrics
+     *
+     * @example
+     * ```typescript
+     * const analytics = await perfService.getAnalytics();
+     * console.log(analytics.by_provider);
+     * ```
+     */
     async getAnalytics() {
         return await this.readSnapshot();
     }
+    /**
+     * Retrieves provider/model statistics with optional filtering.
+     *
+     * @param provider - optional provider filter
+     * @param model - optional model filter
+     * @returns Array of provider/model stats
+     *
+     * @example
+     * ```typescript
+     * const stats = await perfService.getProviderStats('claude');
+     * console.log(stats[0].success_rate);
+     * ```
+     */
     async getProviderStats(provider, model) {
         const snapshot = await this.readSnapshot();
         let stats = snapshot.aggregates;

package/dist/apps/control-plane/application/services/performance-analytics-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"performance-analytics-service.js","sourceRoot":"","sources":["../../../../../apps/control-plane/src/application/services/performance-analytics-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"performance-analytics-service.js","sourceRoot":"","sources":["../../../../../apps/control-plane/src/application/services/performance-analytics-service.ts"],"names":[],"mappings":"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"}

package/dist/apps/control-plane/application/services/plan-service.d.ts

@@ -6,10 +6,44 @@ type StateUpdater = (frontMatter: AnyRecord, body: string) => Promise<{
     frontMatter?: AnyRecord;
     body?: string;
 }>;
+/**
+ * Port interface for plan operations.
+ *
+ * ## Contract
+ * Implementations must ensure:
+ * - Thread-safe access to plan files via feature locks
+ * - Atomic read-modify-write operations for state updates
+ * - Schema validation before persistence
+ * - Version guard enforcement for optimistic concurrency
+ *
+ * ## Error Handling
+ * All methods throw normalized errors with:
+ * - `code` - stable error code from ERROR_CODES
+ * - `message` - human-readable description
+ * - `details` - { retryable, requires_human, suggestions }
+ */
 export interface PlanServicePort {
+    /**
+     * Returns the current policy snapshot.
+     * Must not return null; policy is loaded during kernel initialization.
+     */
     getPolicySnapshot(): AnyRecord;
+    /**
+     * Returns the current gates configuration.
+     */
     getGatesConfig(): AnyRecord;
+    /**
+     * Returns the absolute path to a feature's plan.json file.
+     * Does not check if file exists.
+     *
+     * @param featureId - feature identifier
+     */
     planPath(featureId: string): string;
+    /**
+     * Discovers all canonical feature specs under .aop/features/.
+     *
+     * @returns List of feature IDs with canonical specs
+     */
     featureDiscoverSpecs(): Promise<{
         data: {
             specs: Array<{
@@ -17,34 +51,265 @@ export interface PlanServicePort {
             }>;
         };
     }>;
+    /**
+     * Reads feature state (front matter + body).
+     *
+     * @param featureId - feature identifier
+     * @throws FEATURE_NOT_FOUND - if state.md doesn't exist
+     */
     readState(featureId: string): Promise<StateReadResult>;
+    /**
+     * Validates a value against a named schema.
+     *
+     * @param schemaName - schema identifier (e.g., 'plan', 'state')
+     * @param value - value to validate
+     * @returns Validation result with errors if invalid
+     * @throws SCHEMA_NOT_FOUND - if schema doesn't exist
+     */
     validateSchema(schemaName: string, value: unknown): Promise<{
         valid: boolean;
         errors?: unknown;
     }>;
+    /**
+     * Executes an operation with feature-level lock held.
+     * Serializes concurrent access to feature state.
+     *
+     * @param featureId - feature identifier
+     * @param operation - async operation to execute
+     */
     withFeatureLock<T>(featureId: string, operation: () => Promise<T>): Promise<T>;
+    /**
+     * Executes an operation with index-level lock held.
+     * Serializes concurrent access to global index.
+     *
+     * @param operation - async operation to execute
+     */
     withIndexLock<T>(operation: () => Promise<T>): Promise<T>;
+    /**
+     * Reads the global feature index.
+     *
+     * @returns Index object with active/blocked/merged features, locks, sessions
+     */
     readIndex(): Promise<AnyRecord>;
+    /**
+     * Writes the global feature index atomically.
+     *
+     * @param index - index object to persist
+     */
     writeIndex(index: AnyRecord): Promise<void>;
+    /**
+     * Updates feature state with optimistic concurrency control.
+     *
+     * @param featureId - feature identifier
+     * @param expectedVersion - expected version for concurrency check (null = no check)
+     * @param updater - function that returns updated front matter and/or body
+     * @returns Updated front matter
+     * @throws VERSION_MISMATCH - if expectedVersion doesn't match current version
+     */
     updateState(featureId: string, expectedVersion: number | null, updater: StateUpdater): Promise<AnyRecord>;
 }
+/**
+ * Manages plan submission, validation, and collision detection.
+ *
+ * ## Responsibilities
+ * - Validate plan schema and policy compliance
+ * - Detect file/area/contract collisions with other features
+ * - Enforce lock requirements for protected resources
+ * - Manage plan versioning with optimistic concurrency
+ * - Select appropriate gate profiles based on plan intent
+ *
+ * ## Dependencies
+ * Depends on {@link PlanServicePort} for:
+ * - Policy and schema access
+ * - State and index operations
+ * - File locking primitives
+ *
+ * ## Key Methods
+ * - `planSubmit()` - submit initial plan with full validation
+ * - `planUpdate()` - submit versioned plan revision
+ * - `planGet()` - retrieve accepted plan
+ * - `checkPlanCollision()` - detect collisions with other features
+ * - `assertPlanLocksHeld()` - verify required locks are held
+ *
+ * ## Error Conditions
+ * - SCHEMA_VALIDATION_FAILED - plan fails JSON schema validation
+ * - PLAN_COLLISION - file/area/contract conflicts with another feature
+ * - LOCK_NOT_HELD - required resource locks not acquired
+ * - VERSION_CONFLICT - plan version mismatch (concurrent update)
+ * - DEPENDENCY_CYCLE - circular feature dependencies detected
+ *
+ * ## Thread Safety
+ * All mutations are protected by feature-level or index-level locks.
+ * Concurrent reads are safe. Concurrent writes are serialized.
+ *
+ * @example
+ * ```typescript
+ * const planService = new PlanService(port);
+ *
+ * // Submit initial plan
+ * await planService.planSubmit('my_feature', planData, null);
+ *
+ * // Update plan with version guard
+ * await planService.planUpdate('my_feature', updatedPlan, 1);
+ *
+ * // Check for collisions
+ * const result = await planService.checkPlanCollision('my_feature', planData);
+ * ```
+ *
+ * @see CollisionDetector - for collision detection algorithm
+ * @see GateSelectionService - for gate profile selection
+ */
 export declare class PlanService {
     private readonly port;
     private readonly gateSelectionService;
     constructor(port: PlanServicePort);
+    /**
+     * Retrieves the accepted plan for a feature.
+     *
+     * @param featureId - feature identifier
+     * @returns Plan data wrapped in success response
+     * @throws FILE_NOT_FOUND - plan file does not exist
+     *
+     * @example
+     * ```typescript
+     * const result = await planService.planGet('my_feature');
+     * console.log(result.data.plan);
+     * ```
+     */
     planGet(featureId: string): Promise<{
         data: {
             feature_id: string;
             plan: unknown;
         };
     }>;
+    /**
+     * Collects all accepted plans from discovered features.
+     *
+     * Used for collision detection and dependency analysis.
+     *
+     * @param excludeFeatureId - optional feature to exclude from collection
+     * @returns Array of plan objects
+     *
+     * @example
+     * ```typescript
+     * // Get all plans except current feature
+     * const plans = await planService.collectAcceptedPlans('my_feature');
+     * ```
+     */
     collectAcceptedPlans(excludeFeatureId?: string | null): Promise<AnyRecord[]>;
+    /**
+     * Determines required resource locks based on plan contracts.
+     *
+     * Maps contract modifications to resource identifiers per policy.
+     *
+     * @param plan - plan object with contracts section
+     * @returns Sorted array of required resource identifiers
+     *
+     * @example
+     * ```typescript
+     * const resources = planService.requiredResourcesForPlan(plan);
+     * // ['openapi', 'db_migrations']
+     * ```
+     */
     requiredResourcesForPlan(plan: AnyRecord): string[];
+    /**
+     * Verifies that all required resource locks are held by the feature.
+     *
+     * @param featureId - feature identifier
+     * @param plan - plan object requiring locks
+     * @throws LOCK_NOT_HELD - required locks are not held
+     *
+     * @example
+     * ```typescript
+     * await planService.assertPlanLocksHeld('my_feature', plan);
+     * ```
+     */
     assertPlanLocksHeld(featureId: string, plan: AnyRecord): Promise<void>;
+    /**
+     * Validates plan revision rules for versioning and optimistic concurrency.
+     *
+     * Enforces:
+     * - Initial plans must be version 1 without revision_of
+     * - Updates must increment version and reference previous version
+     * - Version guard must match current plan version
+     *
+     * @param existingPlan - current plan or null for initial submission
+     * @param plan - new plan to validate
+     * @param expectedPlanVersion - expected current version for concurrency guard
+     * @throws PLAN_VALIDATION_FAILED - revision rules violated
+     * @throws VERSION_CONFLICT - version mismatch (concurrent update)
+     */
     validatePlanRevisionRules(existingPlan: AnyRecord | null, plan: AnyRecord, expectedPlanVersion?: number | null): void;
+    /**
+     * Validates plan against JSON schema.
+     *
+     * @param plan - plan object to validate
+     * @throws SCHEMA_VALIDATION_FAILED - plan does not conform to schema
+     *
+     * @example
+     * ```typescript
+     * await planService.validatePlanSchema(planData);
+     * ```
+     */
     validatePlanSchema(plan: AnyRecord): Promise<void>;
+    /**
+     * Detects file, area, and contract collisions with other features.
+     *
+     * Compares plan against all accepted plans to find conflicts.
+     *
+     * @param featureId - feature identifier
+     * @param plan - plan to check for collisions
+     * @returns Collision matrix with conflicts by feature
+     * @throws PLAN_COLLISION - collisions detected (per policy)
+     *
+     * @example
+     * ```typescript
+     * const result = await planService.checkPlanCollision('my_feature', plan);
+     * if (result.data.has_collisions) {
+     *   console.log(result.data.collisions);
+     * }
+     * ```
+     */
     checkPlanCollision(featureId: string, plan: AnyRecord): Promise<unknown>;
+    /**
+     * Validates feature dependencies and detects circular references.
+     *
+     * @param featureId - feature to check (null checks all features)
+     * @throws DEPENDENCY_CYCLE - circular dependency detected
+     *
+     * @example
+     * ```typescript
+     * await planService.checkDependencies('my_feature');
+     * ```
+     */
     checkDependencies(featureId: string | null): Promise<void>;
+    /**
+     * Submits initial plan with full validation pipeline.
+     *
+     * Validation steps:
+     * 1. Schema validation
+     * 2. Revision rules check
+     * 3. Lock requirement verification
+     * 4. Collision detection
+     * 5. Dependency cycle check
+     * 6. Gate profile selection
+     *
+     * @param featureId - feature identifier
+     * @param plan - plan object to submit
+     * @param expectedVersion - expected state version for concurrency guard
+     * @returns Acceptance result with plan version
+     * @throws INVALID_ARGUMENT - missing or invalid plan
+     * @throws SCHEMA_VALIDATION_FAILED - plan schema invalid
+     * @throws LOCK_NOT_HELD - required locks not held
+     * @throws PLAN_COLLISION - collisions detected
+     * @throws DEPENDENCY_CYCLE - circular dependencies
+     *
+     * @example
+     * ```typescript
+     * const result = await planService.planSubmit('my_feature', planData, null);
+     * console.log(`Plan accepted: version ${result.data.plan_version}`);
+     * ```
+     */
     planSubmit(featureId: string | null, plan: AnyRecord | null, expectedVersion?: number | null): Promise<{
         data: {
             feature_id: string | null;
@@ -52,6 +317,28 @@ export declare class PlanService {
             plan_version: number;
         };
     }>;
+    /**
+     * Submits versioned plan revision with full revalidation.
+     *
+     * Requires plan_version to be current_version + 1 and revision_of
+     * to reference current version. Runs full validation pipeline.
+     *
+     * @param featureId - feature identifier
+     * @param plan - updated plan object
+     * @param expectedPlanVersion - expected current plan version
+     * @returns Acceptance result with new plan version
+     * @throws VERSION_CONFLICT - plan version mismatch
+     * @throws PLAN_VALIDATION_FAILED - revision rules violated
+     * @throws SCHEMA_VALIDATION_FAILED - plan schema invalid
+     * @throws LOCK_NOT_HELD - required locks not held
+     * @throws PLAN_COLLISION - collisions detected
+     *
+     * @example
+     * ```typescript
+     * // Update plan from version 1 to version 2
+     * const result = await planService.planUpdate('my_feature', updatedPlan, 1);
+     * ```
+     */
     planUpdate(featureId: string | null, expectedPlanVersion: number | null, plan: AnyRecord | null): Promise<{
         data: {
             feature_id: string | null;