agentic-orchestrator 0.1.0

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

@@ -0,0 +1,302 @@
+import { atomicWriteJson, nowIso, readJson } from '../../core/fs.js';
+import { detectPlanCollisions } from '../../core/collisions.js';
+import { sortResourcesDeterministically } from '../../core/path-rules.js';
+import { ERROR_CODES } from '../../core/error-codes.js';
+import { fail } from '../../core/response.js';
+import { GATE_RESULT, STATUS } from '../../core/constants.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyRecord = Record<string, any>;
+
+type StateReadResult = {
+  frontMatter: AnyRecord;
+};
+
+type StateUpdater = (
+  frontMatter: AnyRecord,
+  body: string
+) => Promise<{ frontMatter?: AnyRecord; body?: string }>;
+
+function asArray<T = unknown>(value: unknown): T[] {
+  return Array.isArray(value) ? (value as T[]) : [];
+}
+
+function normalizeSet(array: string[]): string[] {
+  return [...new Set(array)].sort((a, b) => a.localeCompare(b));
+}
+
+function readObjectField(record: AnyRecord, key: string): AnyRecord {
+  const value = record[key];
+  return value && typeof value === 'object' ? (value as AnyRecord) : {};
+}
+
+function readHeldLocks(frontMatter: AnyRecord): string[] {
+  const locks = readObjectField(frontMatter, 'locks');
+  return asArray<string>(locks.held).filter((item) => typeof item === 'string');
+}
+
+export interface PlanServicePort {
+  getPolicySnapshot(): AnyRecord;
+  planPath(featureId: string): string;
+  featureDiscoverSpecs(): Promise<{ data: { specs: Array<{ feature_id: string }> } }>;
+  readState(featureId: string): Promise<StateReadResult>;
+  validateSchema(schemaName: string, value: unknown): Promise<{ valid: boolean; errors?: unknown }>;
+  withFeatureLock<T>(featureId: string, operation: () => Promise<T>): Promise<T>;
+  withIndexLock<T>(operation: () => Promise<T>): Promise<T>;
+  readIndex(): Promise<AnyRecord>;
+  writeIndex(index: AnyRecord): Promise<void>;
+  updateState(featureId: string, expectedVersion: number | null, updater: StateUpdater): Promise<AnyRecord>;
+}
+
+export class PlanService {
+  private readonly port: PlanServicePort;
+
+  constructor(port: PlanServicePort) {
+    this.port = port;
+  }
+
+  async planGet(featureId: string): Promise<{ data: { feature_id: string; plan: unknown } }> {
+    const plan = await readJson(this.port.planPath(featureId), null);
+    return {
+      data: {
+        feature_id: featureId,
+        plan
+      }
+    };
+  }
+
+  async collectAcceptedPlans(excludeFeatureId: string | null = null): Promise<AnyRecord[]> {
+    const specs = await this.port.featureDiscoverSpecs();
+    const plans: AnyRecord[] = [];
+    for (const item of specs.data.specs) {
+      if (item.feature_id === excludeFeatureId) {
+        continue;
+      }
+      const plan = await readJson(this.port.planPath(item.feature_id), null);
+      if (plan) {
+        plans.push(plan);
+      }
+    }
+    return plans;
+  }
+
+  requiredResourcesForPlan(plan: AnyRecord): string[] {
+    const resources: string[] = [];
+    const policy = this.port.getPolicySnapshot();
+    if (plan.contracts?.openapi === 'modify') {
+      resources.push(policy.locks.contract_to_resource.openapi);
+    }
+    if (plan.contracts?.events === 'modify') {
+      resources.push(policy.locks.contract_to_resource.events);
+    }
+    if (plan.contracts?.db === 'migration') {
+      resources.push(policy.locks.contract_to_resource.db);
+    }
+    return sortResourcesDeterministically(resources);
+  }
+
+  async assertPlanLocksHeld(featureId: string, plan: AnyRecord): Promise<void> {
+    const state = await this.port.readState(featureId);
+    const held = new Set(readHeldLocks(state.frontMatter));
+    const required = await this.requiredResourcesForPlan(plan);
+    const missing = required.filter((resource) => !held.has(resource));
+    if (missing.length > 0) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.LOCK_NOT_HELD, 'Plan requires lock(s) that are not held', {
+          feature_id: featureId,
+          missing_resources: missing,
+          retryable: true,
+          requires_human: false,
+          suggested_next_actions: ['Acquire required locks before submitting plan']
+        })
+      };
+    }
+  }
+
+  validatePlanRevisionRules(existingPlan: AnyRecord | null, plan: AnyRecord, expectedPlanVersion: number | null = null): void {
+    if (!existingPlan) {
+      if (plan.plan_version !== 1 || plan.revision_of != null) {
+        throw {
+          normalizedResponse: fail(ERROR_CODES.PLAN_VALIDATION_FAILED, 'Initial plan must be version 1 without revision_of', {
+            retryable: false,
+            requires_human: true
+          })
+        };
+      }
+      return;
+    }
+
+    if (expectedPlanVersion == null || existingPlan.plan_version !== expectedPlanVersion) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.VERSION_CONFLICT, 'Plan version conflict', {
+          expected_plan_version: expectedPlanVersion,
+          actual_plan_version: existingPlan.plan_version,
+          retryable: true,
+          requires_human: false
+        })
+      };
+    }
+
+    if (plan.plan_version !== expectedPlanVersion + 1 || plan.revision_of !== expectedPlanVersion) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.PLAN_VALIDATION_FAILED, 'Invalid plan revision metadata', {
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+  }
+
+  async validatePlanSchema(plan: AnyRecord): Promise<void> {
+    const validation = await this.port.validateSchema('plan.schema.json', plan);
+    if (!validation.valid) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.PLAN_VALIDATION_FAILED, 'plan.json failed schema validation', {
+          errors: validation.errors,
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+  }
+
+  async checkPlanCollision(featureId: string, plan: AnyRecord): Promise<unknown> {
+    const policy = this.port.getPolicySnapshot();
+    const acceptedPlans = await this.collectAcceptedPlans(featureId);
+    const collisionResult = detectPlanCollisions(
+      plan as Parameters<typeof detectPlanCollisions>[0],
+      acceptedPlans as Parameters<typeof detectPlanCollisions>[1],
+      policy as Parameters<typeof detectPlanCollisions>[2]
+    );
+
+    if (!collisionResult.hasCollisions) {
+      return collisionResult;
+    }
+
+    if (policy.collision_policy === 'reject') {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.COLLISION_DETECTED, 'Plan collides with accepted plans', {
+          feature_id: featureId,
+          collisions: collisionResult.collisions,
+          collision_fingerprint: collisionResult.fingerprint,
+          conflicting_feature_ids: normalizeSet(
+            collisionResult.collisions.files
+              .map((x) => x.with_feature_id)
+              .concat(
+                collisionResult.collisions.areas.map((x) => x.with_feature_id),
+                collisionResult.collisions.contracts.map((x) => x.with_feature_id)
+              )
+          ),
+          retryable: false,
+          requires_human: true,
+          suggested_next_actions: [
+            'Acquire relevant lock and resubmit',
+            'Revise plan scope to avoid overlap',
+            'Create shared prerequisite feature'
+          ]
+        })
+      };
+    }
+
+    await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      index.blocked_queue.push({
+        feature_id: featureId,
+        plan_version: plan.plan_version,
+        detected_at: nowIso(),
+        collision_fingerprint: collisionResult.fingerprint,
+        required_resources: await this.requiredResourcesForPlan(plan),
+        plan_snapshot: plan
+      });
+      index.blocked_queue.sort(
+        (a: AnyRecord, b: AnyRecord) => a.detected_at.localeCompare(b.detected_at) || a.feature_id.localeCompare(b.feature_id)
+      );
+      index.version += 1;
+      index.updated_at = nowIso();
+      await this.port.writeIndex(index);
+    });
+
+    throw {
+      normalizedResponse: fail(ERROR_CODES.BLOCKED_BY_COLLISION_POLICY, 'Plan queued due to collision policy=block', {
+        feature_id: featureId,
+        collision_fingerprint: collisionResult.fingerprint,
+        collisions: collisionResult.collisions,
+        retryable: true,
+        requires_human: false
+      })
+    };
+  }
+
+  async planSubmit(
+    featureId: string | null,
+    plan: AnyRecord | null,
+    expectedVersion: number | null = null
+  ): Promise<{ data: { feature_id: string | null; accepted: boolean; plan_version: number } }> {
+    if (!plan || typeof plan !== 'object') {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.INVALID_ARGUMENT, 'plan_json is required', {
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    if (plan.feature_id !== featureId) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.INVALID_ARGUMENT, 'plan.feature_id must match feature_id', {
+          feature_id: featureId,
+          plan_feature_id: plan.feature_id,
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    await this.validatePlanSchema(plan);
+    await this.assertPlanLocksHeld(featureId, plan);
+
+    const existing = await readJson(this.port.planPath(featureId), null);
+    this.validatePlanRevisionRules(existing, plan, expectedVersion);
+
+    await this.checkPlanCollision(featureId, plan);
+
+    await this.port.withFeatureLock(featureId, async () => {
+      await atomicWriteJson(this.port.planPath(featureId), plan);
+    });
+
+    await this.port.updateState(featureId, null, (frontMatter, body) => {
+      const nextStatus =
+        frontMatter.status === STATUS.PLANNING || frontMatter.status === STATUS.BLOCKED
+          ? STATUS.BUILDING
+          : frontMatter.status;
+      return Promise.resolve({
+        frontMatter: {
+          gate_profile: plan.gate_profile,
+          gates: {
+            ...frontMatter.gates,
+            plan: GATE_RESULT.PASS
+          },
+          status: nextStatus,
+          collisions: {
+            files: [],
+            areas: [],
+            contracts: []
+          }
+        },
+        body
+      });
+    });
+
+    return {
+      data: {
+        feature_id: featureId,
+        accepted: true,
+        plan_version: plan.plan_version
+      }
+    };
+  }
+
+  async planUpdate(featureId: string | null, expectedPlanVersion: number | null, plan: AnyRecord | null) {
+    return await this.planSubmit(featureId, plan, expectedPlanVersion);
+  }
+}

package/apps/control-plane/src/application/services/qa-index-service.ts

@@ -0,0 +1,98 @@
+import { atomicWriteJson, readJson, stableHash } from '../../core/fs.js';
+import { applyQaUpdates, summarizeQaIndex } from '../../core/qa-index.js';
+import { ERROR_CODES } from '../../core/error-codes.js';
+import { fail } from '../../core/response.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyRecord = Record<string, any>;
+
+export interface QaIndexServicePort {
+  qaIndexPath(featureId: string): string;
+  validateSchema(schemaName: string, value: unknown): Promise<{ valid: boolean; errors?: unknown }>;
+}
+
+export class QaIndexService {
+  private readonly port: QaIndexServicePort;
+
+  constructor(port: QaIndexServicePort) {
+    this.port = port;
+  }
+
+  async qaTestIndexGet(featureId: string): Promise<{
+    data: {
+      index: AnyRecord;
+      summary: AnyRecord;
+      pending_required_tests: AnyRecord;
+    };
+  }> {
+    const index = await readJson(this.port.qaIndexPath(featureId), {
+      feature_id: featureId,
+      version: 1,
+      source_diff_ref: stableHash('empty'),
+      items: []
+    });
+
+    const validation = await this.port.validateSchema('qa_test_index.schema.json', index);
+    if (!validation.valid) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.INTERNAL_ERROR, 'qa_test_index file is invalid', {
+          errors: validation.errors,
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    const summary = summarizeQaIndex(index);
+    return {
+      data: {
+        index,
+        summary: summary.summary,
+        pending_required_tests: summary.pending_by_file
+      }
+    };
+  }
+
+  async qaTestIndexUpdate(
+    featureId: string,
+    expectedVersion: number | null,
+    updates: unknown,
+    evidenceRefs: unknown[]
+  ): Promise<{ data: { feature_id: string; version: number } }> {
+    const current = await readJson(this.port.qaIndexPath(featureId), null);
+    if (!current) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.FILE_NOT_FOUND, 'qa_test_index.json not found', {
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    const next = applyQaUpdates(
+      current,
+      expectedVersion,
+      updates as Parameters<typeof applyQaUpdates>[2],
+      evidenceRefs as Parameters<typeof applyQaUpdates>[3]
+    );
+    const validation = await this.port.validateSchema('qa_test_index.schema.json', next);
+    if (!validation.valid) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.INTERNAL_ERROR, 'qa_test_index update failed validation', {
+          errors: validation.errors,
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    await atomicWriteJson(this.port.qaIndexPath(featureId), next);
+
+    return {
+      data: {
+        feature_id: featureId,
+        version: next.version
+      }
+    };
+  }
+}

package/apps/control-plane/src/application/services/reporting-service.ts

@@ -0,0 +1,120 @@
+import { detectPlanCollisions } from '../../core/collisions.js';
+import { pathExists, stableHash } from '../../core/fs.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyRecord = Record<string, any>;
+
+function normalizeSet(array: string[]): string[] {
+  return [...new Set(array)].sort((a, b) => a.localeCompare(b));
+}
+
+function readHeldLocks(frontMatter: AnyRecord): string[] {
+  const locks = frontMatter?.locks && typeof frontMatter.locks === 'object' ? frontMatter.locks : {};
+  const held = Array.isArray(locks.held) ? locks.held : [];
+  return held.filter((item: unknown): item is string => typeof item === 'string');
+}
+
+function createCollisionFingerprint(collisions: unknown): string {
+  return stableHash(JSON.stringify(collisions));
+}
+
+export interface ReportingServicePort {
+  collectAcceptedPlans(excludeFeatureId?: string | null): Promise<AnyRecord[]>;
+  getPolicySnapshot(): AnyRecord;
+  readIndex(): Promise<AnyRecord>;
+  statePath(featureId: string): string;
+  readState(featureId: string): Promise<{ frontMatter: AnyRecord }>;
+  featureStateGet(featureId: string): Promise<{ data: { front_matter: AnyRecord } }>;
+  repoDiffBundle(featureId: string): Promise<{ data: AnyRecord }>;
+  qaTestIndexGet(featureId: string): Promise<{ data: AnyRecord }>;
+}
+
+export class ReportingService {
+  private readonly port: ReportingServicePort;
+
+  constructor(port: ReportingServicePort) {
+    this.port = port;
+  }
+
+  async collisionsScan() {
+    const plans = await this.port.collectAcceptedPlans();
+    const matrix = [];
+
+    for (let i = 0; i < plans.length; i += 1) {
+      for (let j = i + 1; j < plans.length; j += 1) {
+        const candidatePlan = plans[i] as Parameters<typeof detectPlanCollisions>[0];
+        const comparisonPlan = plans[j] as Parameters<typeof detectPlanCollisions>[0];
+        const result = detectPlanCollisions(
+          candidatePlan,
+          [comparisonPlan],
+          this.port.getPolicySnapshot() as Parameters<typeof detectPlanCollisions>[2]
+        );
+        if (result.hasCollisions) {
+          matrix.push({
+            feature_id: candidatePlan.feature_id,
+            with_feature_id: comparisonPlan.feature_id,
+            collisions: result.collisions,
+            fingerprint: createCollisionFingerprint(result.collisions)
+          });
+        }
+      }
+    }
+
+    return {
+      data: {
+        collisions: matrix
+      }
+    };
+  }
+
+  async reportDashboard() {
+    const index = await this.port.readIndex();
+    const featureIds = normalizeSet([
+      ...index.active,
+      ...index.blocked,
+      ...index.merged,
+      ...Object.values(index.locks).filter(Boolean)
+    ]);
+
+    const features = [];
+    for (const featureId of featureIds) {
+      const statePath = this.port.statePath(featureId);
+      if (!(await pathExists(statePath))) {
+        continue;
+      }
+      const state = await this.port.readState(featureId);
+      features.push({
+        feature_id: featureId,
+        status: state.frontMatter.status,
+        locks: readHeldLocks(state.frontMatter),
+        gate_profile: state.frontMatter.gate_profile,
+        gates: state.frontMatter.gates,
+        last_updated: state.frontMatter.last_updated
+      });
+    }
+
+    return {
+      data: {
+        index,
+        features
+      }
+    };
+  }
+
+  async reportFeatureSummary(featureId: string | null) {
+    const state = await this.port.featureStateGet(featureId as unknown as string);
+    const bundle = await this.port.repoDiffBundle(featureId as unknown as string);
+    const qa = await this.port.qaTestIndexGet(featureId as unknown as string);
+
+    return {
+      data: {
+        feature_id: featureId,
+        state: state.data.front_matter,
+        diff_stat: bundle.data.diff_stat,
+        touched_files: bundle.data.touched_files,
+        last_gate_summary: bundle.data.last_gate_summary,
+        qa_summary: qa.data.summary
+      }
+    };
+  }
+}