@principal-ai/subsystems-core 0.29.0 → 0.30.0

package/src/ValidationEngine.ts

@@ -1,200 +0,0 @@
-import type {
-  EdgeEvent,
-  GraphEvent,
-  GraphState,
-  StateEvent,
-  ValidationResult,
-  ValidationRules,
-  Violation,
-  Warning,
-} from './types';
-
-/**
- * ValidationEngine checks events against defined rules
- */
-export class ValidationEngine {
-  private rules: ValidationRules;
-  private violationCount = 0;
-  private warningCount = 0;
-
-  constructor(rules: ValidationRules) {
-    this.rules = rules;
-  }
-
-  /**
-   * Validate an event against all rules
-   */
-  validate(event: GraphEvent, state: GraphState): ValidationResult {
-    const violations: Violation[] = [];
-    const warnings: Warning[] = [];
-
-    // Check connection rules
-    if (event.category === 'edge' && event.operation === 'create') {
-      violations.push(...this.validateConnection(event, state));
-    }
-
-    // Check state transition rules
-    if (event.category === 'state') {
-      violations.push(...this.validateStateTransition(event, state));
-    }
-
-    // Check if event was expected
-    if (event.expected === false) {
-      violations.push(this.createUnexpectedEventViolation(event));
-    }
-
-    // Update counters
-    this.violationCount += violations.filter((v) => v.severity === 'error').length;
-    this.warningCount += violations.filter((v) => v.severity === 'warning').length;
-
-    return {
-      valid: violations.filter((v) => v.severity === 'error').length === 0,
-      violations,
-      warnings,
-      metrics: {
-        totalEvents: 1,
-        validEvents: violations.length === 0 ? 1 : 0,
-        violations: violations.filter((v) => v.severity === 'error').length,
-        warnings: violations.filter((v) => v.severity === 'warning').length,
-        unexpectedEvents: event.expected === false ? 1 : 0,
-        expectedEventsMissing: 0,
-      },
-    };
-  }
-
-  /**
-   * Check constraints across the entire graph state
-   */
-  checkConstraints(state: GraphState): Violation[] {
-    const violations: Violation[] = [];
-
-    // Check cardinality constraints
-    if (this.rules.cardinality) {
-      for (const [nodeType, rule] of Object.entries(this.rules.cardinality)) {
-        const count = Array.from(state.nodes.values()).filter((n) => n.type === nodeType).length;
-
-        if (rule.min !== undefined && count < rule.min) {
-          violations.push({
-            id: `cardinality-${nodeType}-min`,
-            severity: 'error',
-            type: 'cardinality',
-            description: `Node type '${nodeType}' has ${count} instances but requires at least ${rule.min}`,
-          });
-        }
-
-        if (rule.max !== undefined && count > rule.max) {
-          violations.push({
-            id: `cardinality-${nodeType}-max`,
-            severity: 'error',
-            type: 'cardinality',
-            description: `Node type '${nodeType}' has ${count} instances but allows at most ${rule.max}`,
-          });
-        }
-      }
-    }
-
-    return violations;
-  }
-
-  /**
-   * Validate connection rules
-   */
-  private validateConnection(event: GraphEvent, state: GraphState): Violation[] {
-    const violations: Violation[] = [];
-    const payload = event.payload as EdgeEvent;
-
-    // Get the nodes being connected
-    const fromNode = state.nodes.get(payload.from);
-    const toNode = state.nodes.get(payload.to);
-
-    if (!fromNode || !toNode) {
-      violations.push({
-        id: `connection-${event.id}`,
-        severity: 'error',
-        type: 'connection',
-        description: 'Cannot create edge: one or both nodes do not exist',
-        event,
-        context: {
-          edgeId: payload.edgeId,
-        },
-      });
-      return violations;
-    }
-
-    // Check if this connection is allowed
-    const allowedConnections = state.configuration.allowedConnections || [];
-    const isAllowed = allowedConnections.some(
-      (rule) =>
-        rule.from === fromNode.type && rule.to === toNode.type && rule.via === payload.edgeType
-    );
-
-    if (!isAllowed) {
-      violations.push({
-        id: `connection-${event.id}`,
-        severity: 'error',
-        type: 'connection',
-        description: `Connection from '${fromNode.type}' to '${toNode.type}' via '${payload.edgeType}' is not allowed`,
-        event,
-        context: {
-          edgeId: payload.edgeId,
-        },
-      });
-    }
-
-    return violations;
-  }
-
-  /**
-   * Validate state transitions
-   */
-  private validateStateTransition(event: GraphEvent, state: GraphState): Violation[] {
-    const violations: Violation[] = [];
-    const payload = event.payload as StateEvent;
-
-    const node = state.nodes.get(payload.nodeId);
-    if (!node) {
-      return violations;
-    }
-
-    const transitions = this.rules.stateTransitions?.[node.type];
-    if (!transitions) {
-      return violations;
-    }
-
-    const currentState = payload.previousState || node.state;
-    const newState = payload.newState;
-
-    // Find valid transitions from current state
-    const validTransition = transitions.find((t) => t.from === currentState);
-
-    if (validTransition && !validTransition.to.includes(newState)) {
-      violations.push({
-        id: `state-transition-${event.id}`,
-        severity: 'error',
-        type: 'state',
-        description: `Invalid state transition for '${
-          node.type
-        }': ${currentState} -> ${newState}. Valid transitions: ${validTransition.to.join(', ')}`,
-        event,
-        context: {
-          nodeId: payload.nodeId,
-        },
-      });
-    }
-
-    return violations;
-  }
-
-  /**
-   * Create violation for unexpected event
-   */
-  private createUnexpectedEventViolation(event: GraphEvent): Violation {
-    return {
-      id: `unexpected-${event.id}`,
-      severity: 'warning',
-      type: 'unexpected_event',
-      description: `Unexpected event: ${event.type}`,
-      event,
-    };
-  }
-}

package/src/auxiliary/AuxiliaryManifestValidator.test.ts

@@ -1,93 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { mkdtempSync, mkdirSync, writeFileSync } from 'fs';
-import { tmpdir } from 'os';
-import { join } from 'path';
-import { NodeFileSystemAdapter } from '@principal-ai/repository-abstraction/node';
-import { AuxiliaryManifestValidator } from './AuxiliaryManifestValidator';
-import type { AuxiliaryManifest } from '../types/auxiliary';
-
-function makeRepo(layout: string[]): string {
-  const root = mkdtempSync(join(tmpdir(), 'aux-manifest-'));
-  for (const rel of layout) {
-    const full = join(root, rel);
-    mkdirSync(full.substring(0, full.lastIndexOf('/')) || full, { recursive: true });
-    if (!rel.endsWith('/')) writeFileSync(full, '');
-  }
-  return root;
-}
-
-describe('AuxiliaryManifestValidator', () => {
-  const validator = new AuxiliaryManifestValidator(new NodeFileSystemAdapter());
-
-  test('no manifest is a no-op', async () => {
-    const result = await validator.validate({ basePath: '/tmp' });
-    expect(result.valid).toBe(true);
-    expect(result.violations).toHaveLength(0);
-  });
-
-  test('passes for a clean manifest', async () => {
-    const root = makeRepo(['docs/README.md', '.github/workflows/ci.yml']);
-    const manifest: AuxiliaryManifest = {
-      areas: [
-        { name: 'Documentation', paths: ['docs'], description: 'design docs' },
-        { name: 'GitHub', paths: ['.github'], description: 'CI config' },
-      ],
-    };
-    const result = await validator.validate({ manifest, basePath: root });
-    expect(result.valid).toBe(true);
-    expect(result.violations).toHaveLength(0);
-  });
-
-  test('flags duplicate area names', async () => {
-    const root = makeRepo(['docs/README.md', 'misc/note.txt']);
-    const manifest: AuxiliaryManifest = {
-      areas: [
-        { name: 'Docs', paths: ['docs'], description: 'a' },
-        { name: 'Docs', paths: ['misc'], description: 'b' },
-      ],
-    };
-    const result = await validator.validate({ manifest, basePath: root });
-    const dup = result.violations.find((v) => v.ruleId === 'auxiliary-area-name-duplicate');
-    expect(dup).toBeDefined();
-    expect(dup!.severity).toBe('error');
-    expect(result.valid).toBe(false);
-  });
-
-  test('warns when a declared path does not exist', async () => {
-    const root = makeRepo(['docs/README.md']);
-    const manifest: AuxiliaryManifest = {
-      areas: [{ name: 'Ghost', paths: ['nope'], description: 'missing' }],
-    };
-    const result = await validator.validate({ manifest, basePath: root });
-    const missing = result.violations.find((v) => v.ruleId === 'auxiliary-area-path-missing');
-    expect(missing).toBeDefined();
-    expect(missing!.severity).toBe('warn');
-    // Warnings alone don't invalidate the manifest
-    expect(result.valid).toBe(true);
-  });
-
-  test('flags overlap between two areas', async () => {
-    const root = makeRepo(['docs/sub/file.md']);
-    const manifest: AuxiliaryManifest = {
-      areas: [
-        { name: 'A', paths: ['docs'], description: 'a' },
-        { name: 'B', paths: ['docs/sub'], description: 'b' },
-      ],
-    };
-    const result = await validator.validate({ manifest, basePath: root });
-    const overlap = result.violations.find((v) => v.ruleId === 'auxiliary-area-paths-overlap');
-    expect(overlap).toBeDefined();
-    expect(overlap!.severity).toBe('error');
-    expect(result.valid).toBe(false);
-  });
-
-  test('flags duplicate paths within a single area as self-overlap', async () => {
-    const root = makeRepo(['docs/file.md']);
-    const manifest: AuxiliaryManifest = {
-      areas: [{ name: 'A', paths: ['docs', 'docs'], description: 'a' }],
-    };
-    const result = await validator.validate({ manifest, basePath: root });
-    const self = result.violations.find((v) => v.ruleId === 'auxiliary-area-paths-self-overlap');
-    expect(self).toBeDefined();
-  });
-});

package/src/auxiliary/AuxiliaryManifestValidator.ts

@@ -1,132 +0,0 @@
-/**
- * Auxiliary Manifest Validator
- *
- * Own-file checks for `.principal-views/auxiliary.manifest.json`:
- *   - area names are unique
- *   - declared paths exist on disk
- *   - paths don't overlap each other (within or across areas)
- *
- * Cross-file overlap with scope paths lives in `validateAreaScopeDisjoint`,
- * mirroring the way `validateScopeNamespaceNesting` handles cross-canvas
- * checks for scopes/namespaces.
- */
-
-import type { FileSystemAdapter } from '@principal-ai/repository-abstraction';
-import type { AuxiliaryManifest } from '../types/auxiliary';
-import { pathsOverlap } from '../events/path-helpers';
-
-export interface AuxiliaryManifestValidationContext {
-  /** Parsed manifest. When absent, validation is a no-op (manifest is optional). */
-  manifest?: AuxiliaryManifest;
-
-  /** Path to the manifest file — used in violation messages. */
-  manifestPath?: string;
-
-  /** Repo root for resolving area paths against the filesystem. */
-  basePath: string;
-}
-
-export interface AuxiliaryManifestViolation {
-  ruleId: string;
-  severity: 'error' | 'warn';
-  file: string;
-  path?: string;
-  message: string;
-  impact: string;
-  suggestion: string;
-}
-
-export interface AuxiliaryManifestValidationResult {
-  valid: boolean;
-  violations: AuxiliaryManifestViolation[];
-}
-
-const DEFAULT_MANIFEST_PATH = '.principal-views/auxiliary.manifest.json';
-
-export class AuxiliaryManifestValidator {
-  constructor(private fsAdapter: FileSystemAdapter) {}
-
-  async validate(context: AuxiliaryManifestValidationContext): Promise<AuxiliaryManifestValidationResult> {
-    const violations: AuxiliaryManifestViolation[] = [];
-    const { manifest, basePath } = context;
-    const file = context.manifestPath || DEFAULT_MANIFEST_PATH;
-
-    if (!manifest) {
-      return { valid: true, violations };
-    }
-
-    const areas = manifest.areas || [];
-
-    // Unique area names
-    const seenNames = new Map<string, number>();
-    areas.forEach((area, idx) => {
-      const count = seenNames.get(area.name) ?? 0;
-      seenNames.set(area.name, count + 1);
-      if (count === 1) {
-        violations.push({
-          ruleId: 'auxiliary-area-name-duplicate',
-          severity: 'error',
-          file,
-          path: `areas[${idx}].name`,
-          message: `Area name "${area.name}" is declared more than once`,
-          impact: 'Duplicate names make diagnostics ambiguous — a violation cannot be tied back to a single area',
-          suggestion: 'Rename one of the areas so names are unique across the manifest.',
-        });
-      }
-    });
-
-    // Path existence + collect for overlap pass
-    const declaredPaths: Array<{ areaName: string; areaIndex: number; pathIndex: number; path: string }> = [];
-    for (let areaIdx = 0; areaIdx < areas.length; areaIdx++) {
-      const area = areas[areaIdx];
-      const paths = area.paths || [];
-      for (let pathIdx = 0; pathIdx < paths.length; pathIdx++) {
-        const p = paths[pathIdx];
-        declaredPaths.push({ areaName: area.name, areaIndex: areaIdx, pathIndex: pathIdx, path: p });
-
-        const resolved = this.fsAdapter.join(basePath, p);
-        if (!(await this.fsAdapter.exists(resolved))) {
-          violations.push({
-            ruleId: 'auxiliary-area-path-missing',
-            severity: 'warn',
-            file,
-            path: `areas[${areaIdx}].paths[${pathIdx}]`,
-            message: `Path "${p}" declared by area "${area.name}" does not exist`,
-            impact: 'The manifest documents a folder that is not present in the repository',
-            suggestion: 'Verify the path exists relative to the repository root, or remove it from the area declaration.',
-          });
-        }
-      }
-    }
-
-    // Path overlap. Unlike scopes, areas have no dotted-name hierarchy, so
-    // parent-child nesting between two areas is just as ambiguous as a flat
-    // overlap — both are flagged.
-    for (let i = 0; i < declaredPaths.length; i++) {
-      for (let j = i + 1; j < declaredPaths.length; j++) {
-        const a = declaredPaths[i];
-        const b = declaredPaths[j];
-        const relationship = pathsOverlap(a.path, b.path);
-        if (relationship === 'none') continue;
-
-        const sameArea = a.areaName === b.areaName;
-        violations.push({
-          ruleId: sameArea ? 'auxiliary-area-paths-self-overlap' : 'auxiliary-area-paths-overlap',
-          severity: 'error',
-          file,
-          path: sameArea
-            ? `areas[${a.areaIndex}].paths`
-            : undefined,
-          message: sameArea
-            ? `Area "${a.areaName}" declares overlapping paths "${a.path}" and "${b.path}"`
-            : `Paths overlap between areas "${a.areaName}" ("${a.path}") and "${b.areaName}" ("${b.path}")`,
-          impact: 'Two area declarations covering the same file make ownership ambiguous',
-          suggestion: 'Make the paths disjoint. If one folder genuinely sits inside another area, drop the redundant entry.',
-        });
-      }
-    }
-
-    const errors = violations.filter((v) => v.severity === 'error');
-    return { valid: errors.length === 0, violations };
-  }
-}

package/src/auxiliary/index.ts

@@ -1,18 +0,0 @@
-/**
- * Auxiliary module
- *
- * Validation for `auxiliary.manifest.json` — the catalog of project regions
- * that sit outside the OTEL telemetry surface (docs, .github, etc.).
- */
-
-export {
-  AuxiliaryManifestValidator,
-  type AuxiliaryManifestValidationContext,
-  type AuxiliaryManifestValidationResult,
-  type AuxiliaryManifestViolation,
-} from './AuxiliaryManifestValidator';
-
-export {
-  validateAreaScopeDisjoint,
-  type ValidateAreaScopeDisjointInput,
-} from './validateAreaScopeDisjoint';

package/src/auxiliary/validateAreaScopeDisjoint.test.ts

@@ -1,85 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { validateAreaScopeDisjoint } from './validateAreaScopeDisjoint';
-import type { AuxiliaryManifest } from '../types/auxiliary';
-import type { ExtendedCanvas } from '../types/canvas';
-
-function scopesCanvas(nodes: Array<{ scope: string; paths?: string[] }>): ExtendedCanvas {
-  return {
-    nodes: nodes.map((n, i) => ({
-      id: `s${i}`,
-      type: 'otel-scope',
-      description: `${n.scope} scope`,
-      ...(n.paths !== undefined ? { paths: n.paths } : {}),
-      otel: { scope: n.scope },
-      x: 0, y: 0, width: 100, height: 50,
-    })),
-    edges: [],
-  } as ExtendedCanvas;
-}
-
-describe('validateAreaScopeDisjoint', () => {
-  test('returns no violations when areas and scopes are disjoint', () => {
-    const manifest: AuxiliaryManifest = {
-      areas: [{ name: 'Docs', paths: ['docs'], description: 'd' }],
-    };
-    const violations = validateAreaScopeDisjoint({
-      manifest,
-      scopesCanvas: scopesCanvas([{ scope: 'core', paths: ['packages/subsystems-core/src'] }]),
-    });
-    expect(violations).toHaveLength(0);
-  });
-
-  test('flags exact overlap with a scope path', () => {
-    const manifest: AuxiliaryManifest = {
-      areas: [{ name: 'Core', paths: ['packages/subsystems-core/src'], description: 'd' }],
-    };
-    const violations = validateAreaScopeDisjoint({
-      manifest,
-      scopesCanvas: scopesCanvas([{ scope: 'core', paths: ['packages/subsystems-core/src'] }]),
-    });
-    expect(violations).toHaveLength(1);
-    expect(violations[0].ruleId).toBe('auxiliary-area-scope-overlap');
-  });
-
-  test('flags parent-child overlap (area covering a scope path)', () => {
-    const manifest: AuxiliaryManifest = {
-      areas: [{ name: 'All', paths: ['packages'], description: 'd' }],
-    };
-    const violations = validateAreaScopeDisjoint({
-      manifest,
-      scopesCanvas: scopesCanvas([{ scope: 'core', paths: ['packages/subsystems-core/src'] }]),
-    });
-    expect(violations).toHaveLength(1);
-    expect(violations[0].ruleId).toBe('auxiliary-area-scope-overlap');
-  });
-
-  test('flags parent-child overlap (scope path covering an area)', () => {
-    const manifest: AuxiliaryManifest = {
-      areas: [{ name: 'Inner', paths: ['packages/subsystems-core/src/docs'], description: 'd' }],
-    };
-    const violations = validateAreaScopeDisjoint({
-      manifest,
-      scopesCanvas: scopesCanvas([{ scope: 'core', paths: ['packages/subsystems-core/src'] }]),
-    });
-    expect(violations).toHaveLength(1);
-  });
-
-  test('no scopes canvas means no cross-check', () => {
-    const manifest: AuxiliaryManifest = {
-      areas: [{ name: 'Docs', paths: ['docs'], description: 'd' }],
-    };
-    const violations = validateAreaScopeDisjoint({ manifest });
-    expect(violations).toHaveLength(0);
-  });
-
-  test('scopes without paths impose no constraint', () => {
-    const manifest: AuxiliaryManifest = {
-      areas: [{ name: 'Docs', paths: ['docs'], description: 'd' }],
-    };
-    const violations = validateAreaScopeDisjoint({
-      manifest,
-      scopesCanvas: scopesCanvas([{ scope: 'core' }]),
-    });
-    expect(violations).toHaveLength(0);
-  });
-});

package/src/auxiliary/validateAreaScopeDisjoint.ts

@@ -1,72 +0,0 @@
-/**
- * Area / Scope Disjointness Validator
- *
- * Cross-file check: project-area paths declared in
- * `auxiliary.manifest.json` must be disjoint from every scope path declared
- * in `architecture.scopes.canvas`. Areas and scopes carve up the repo into
- * non-overlapping regions — any overlap (parent-child or otherwise) means a
- * file is claimed by both an OTEL scope and an auxiliary area, which makes
- * ownership ambiguous.
- *
- * Mirrors `validateScopeNamespaceNesting`'s cross-canvas pattern: takes both
- * inputs, returns violations.
- */
-
-import type { AuxiliaryManifest } from '../types/auxiliary';
-import type { ExtendedCanvas } from '../types/canvas';
-import { isOtelScopeNode } from '../types/canvas';
-import { pathsOverlap } from '../events/path-helpers';
-import type { AuxiliaryManifestViolation } from './AuxiliaryManifestValidator';
-
-export interface ValidateAreaScopeDisjointInput {
-  manifest: AuxiliaryManifest;
-  manifestPath?: string;
-  scopesCanvas?: ExtendedCanvas;
-  scopesCanvasPath?: string;
-}
-
-const DEFAULT_MANIFEST_PATH = '.principal-views/auxiliary.manifest.json';
-
-export function validateAreaScopeDisjoint(
-  input: ValidateAreaScopeDisjointInput,
-): AuxiliaryManifestViolation[] {
-  const { manifest, scopesCanvas } = input;
-  const manifestFile = input.manifestPath || DEFAULT_MANIFEST_PATH;
-
-  if (!scopesCanvas) return [];
-
-  const scopePaths: Array<{ scope: string; path: string }> = [];
-  for (const node of scopesCanvas.nodes || []) {
-    if (!isOtelScopeNode(node)) continue;
-    const scope = node.otel?.scope;
-    const paths = node.paths;
-    if (!scope || !paths || paths.length === 0) continue;
-    for (const p of paths) scopePaths.push({ scope, path: p });
-  }
-
-  if (scopePaths.length === 0) return [];
-
-  const violations: AuxiliaryManifestViolation[] = [];
-  const areas = manifest.areas || [];
-
-  areas.forEach((area, areaIdx) => {
-    (area.paths || []).forEach((areaPath, pathIdx) => {
-      for (const sp of scopePaths) {
-        const relationship = pathsOverlap(areaPath, sp.path);
-        if (relationship === 'none') continue;
-
-        violations.push({
-          ruleId: 'auxiliary-area-scope-overlap',
-          severity: 'error',
-          file: manifestFile,
-          path: `areas[${areaIdx}].paths[${pathIdx}]`,
-          message: `Area "${area.name}" path "${areaPath}" overlaps scope "${sp.scope}" path "${sp.path}"`,
-          impact: 'A file claimed by both an OTEL scope and an auxiliary area has ambiguous ownership — the manifest is meant to catalog regions outside the telemetry surface',
-          suggestion: 'Make the area path disjoint from every scope path. If the folder is genuinely runtime code, drop it from the manifest; if it is auxiliary, narrow the scope path or move the folder.',
-        });
-      }
-    });
-  });
-
-  return violations;
-}