@principal-ai/subsystems-core 0.29.0

package/src/ValidationEngine.ts

@@ -0,0 +1,200 @@
+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/agent-sessions/fixture.ts

@@ -0,0 +1,225 @@
+import path from "node:path";
+import {
+  accumulateToAgentSessionEvents,
+  type AgentSessionEvent,
+  type NormalizedPathInfo,
+  type RepoNormalizedUniversalAgentSessionEvent,
+} from "@principal-ai/agent-monitoring";
+
+/**
+ * Frozen File City agent-session fixture generation.
+ *
+ * Reproduces the shape the file-city-panel fixture loaders consume
+ * (`{ generatedFrom, session, events }`): repo-normalized universal events are
+ * accumulated into agent-session events, then layer item paths (repo-relative
+ * displayPaths) are rewritten back to absolute paths with a per-repo
+ * files/edits manifest. The result is a static snapshot — no pipeline runs at
+ * story time.
+ */
+
+export interface AgentSessionFixtureMeta {
+  sessionName: string;
+  sessionTask: string;
+  workingDirectory: string;
+  createdAt?: string;
+}
+
+export interface AgentSessionFixtureRepo {
+  repo: string;
+  root: string;
+  files: number;
+  edits: number;
+}
+
+export interface AgentSessionFixtureSummary {
+  sessionId: string;
+  agent: string;
+  sessionName: string;
+  sessionTask: string;
+  workingDirectory: string;
+  rawEventCount: number;
+  agentEventCount: number;
+  repos: AgentSessionFixtureRepo[];
+  /** Distinct model ids the session used, in first-use order. */
+  models?: string[];
+}
+
+export interface FixtureLayerItem {
+  path: string;
+  type: "file" | "directory";
+  renderStrategy?: "border" | "fill" | "glow" | "pattern" | "cover" | "icon" | "custom";
+}
+
+export interface FixtureHighlightLayer {
+  id: string;
+  name: string;
+  enabled: boolean;
+  color: string;
+  opacity?: number;
+  borderWidth?: number;
+  priority: number;
+  dynamic?: boolean;
+  items: FixtureLayerItem[];
+}
+
+export interface FixtureAgentSessionEvent {
+  id: string;
+  timestamp: number;
+  sessionId: string;
+  sessionName: string;
+  sessionColor: string;
+  operation: AgentSessionEvent["operation"];
+  files: string[];
+  dependencies: string[];
+  description: string;
+  layers: FixtureHighlightLayer[];
+  contextTokens?: number;
+  subagentType?: string;
+  childSessionId?: string;
+  toolName?: string;
+}
+
+export interface AgentSessionFixture {
+  generatedFrom: string;
+  session: AgentSessionFixtureSummary;
+  events: FixtureAgentSessionEvent[];
+}
+
+function repoLabel(nf: { repository?: { gitRoot?: string; repo?: string } }): string {
+  if (nf.repository?.repo) return nf.repository.repo;
+  if (nf.repository?.gitRoot) return path.basename(nf.repository.gitRoot);
+  return "";
+}
+
+function repoRoot(nf: { repository?: { gitRoot?: string } }): string {
+  return nf.repository?.gitRoot ?? "";
+}
+
+/**
+ * Extract a model id from a model value — agents set it inconsistently
+ * (opencode stores `{ providerID, modelID }`-shaped objects, cline / grok /
+ * pi store a plain string id).
+ */
+function modelIdOf(value: unknown): string | undefined {
+  if (typeof value === "string" && value.length > 0) return value;
+  if (value && typeof value === "object") {
+    const o = value as Record<string, unknown>;
+    for (const key of ["modelID", "id"]) {
+      if (typeof o[key] === "string" && (o[key] as string).length > 0) {
+        return o[key] as string;
+      }
+    }
+  }
+  return undefined;
+}
+
+/** Pull the model id from one event — normalized `data.model` first, then the
+ *  raw opencode `info` blob (the bridge only copies `info.model` onto
+ *  normalized events when the session's created event carried it). */
+function eventModelId(e: RepoNormalizedUniversalAgentSessionEvent): string | undefined {
+  const direct = modelIdOf(e.data?.["model"]);
+  if (direct) return direct;
+  const raw = e.raw as { data?: { info?: { model?: unknown } } } | undefined;
+  return modelIdOf(raw?.data?.info?.model);
+}
+
+/** Distinct model ids across a session's events, in first-seen order. */
+function collectModels(events: RepoNormalizedUniversalAgentSessionEvent[]): string[] {
+  const seen = new Set<string>();
+  const models: string[] = [];
+  for (const e of events) {
+    const id = eventModelId(e);
+    if (id && !seen.has(id)) {
+      seen.add(id);
+      models.push(id);
+    }
+  }
+  return models;
+}
+
+export function buildAgentSessionFixture(options: {
+  agent: string;
+  sessionId: string;
+  sessionMeta: AgentSessionFixtureMeta;
+  normalizedEvents: RepoNormalizedUniversalAgentSessionEvent[];
+  rawEventCount?: number;
+}): AgentSessionFixture {
+  const { agent, sessionId, sessionMeta, normalizedEvents, rawEventCount } = options;
+  const sessionName = sessionMeta.sessionName || "opencode";
+  const agentEvents = accumulateToAgentSessionEvents(normalizedEvents, sessionName);
+
+  // Rewrite layer item paths (repo-relative displayPath) back to absolute
+  // paths. Layer snapshots reflect accumulated state across events, so build a
+  // global displayPath -> absolutePath map from every event's files/dependencies.
+  const repoBreakdown = new Map<string, { root: string; files: Set<string>; edits: Set<string> }>();
+  const displayToAbs = new Map<string, string>();
+
+  for (const e of agentEvents) {
+    for (const f of [...e.files, ...e.dependencies]) {
+      if (typeof f === "object" && f && "displayPath" in f) {
+        const nf = f as NormalizedPathInfo;
+        if (nf.displayPath && !displayToAbs.has(nf.displayPath)) {
+          displayToAbs.set(nf.displayPath, nf.absolutePath);
+        }
+        const label = repoLabel(nf);
+        if (!repoBreakdown.has(label)) {
+          repoBreakdown.set(label, { root: repoRoot(nf), files: new Set(), edits: new Set() });
+        }
+        repoBreakdown.get(label)!.files.add(nf.absolutePath);
+        if (!repoBreakdown.get(label)!.root) repoBreakdown.get(label)!.root = repoRoot(nf);
+      }
+    }
+  }
+
+  const events: FixtureAgentSessionEvent[] = agentEvents.map((e) => {
+    const files = e.files.map((f) =>
+      typeof f === "string" ? f : (f as NormalizedPathInfo).absolutePath,
+    );
+    const dependencies = e.dependencies.map((f) =>
+      typeof f === "string" ? f : (f as NormalizedPathInfo).absolutePath,
+    );
+
+    if (e.operation === "editing") {
+      for (const f of files) {
+        const label = [...repoBreakdown.entries()].find(([, v]) => v.files.has(f))?.[0] ?? "";
+        if (!repoBreakdown.has(label)) {
+          repoBreakdown.set(label, { root: "", files: new Set(), edits: new Set() });
+        }
+        repoBreakdown.get(label)!.edits.add(f);
+      }
+    }
+
+    const layers = e.layers.map((l) => ({
+      ...l,
+      items: l.items.map((item) => {
+        const abs = item.path.startsWith("/") ? item.path : displayToAbs.get(item.path) ?? item.path;
+        return { ...item, path: abs };
+      }),
+    }));
+
+    return { ...e, files, dependencies, layers };
+  });
+
+  const session: AgentSessionFixtureSummary = {
+    sessionId,
+    agent,
+    sessionName,
+    sessionTask: sessionMeta.sessionTask,
+    workingDirectory: sessionMeta.workingDirectory,
+    rawEventCount: rawEventCount ?? normalizedEvents.length,
+    agentEventCount: events.length,
+    repos: [...repoBreakdown.entries()].map(([repo, v]) => ({
+      repo,
+      root: v.root,
+      files: v.files.size,
+      edits: v.edits.size,
+    })),
+    models: collectModels(normalizedEvents),
+  };
+
+  return {
+    generatedFrom: `${agent} session ${sessionId}`,
+    session,
+    events,
+  };
+}

package/src/agent-sessions/index.ts

@@ -0,0 +1,10 @@
+export { buildAgentSessionFixture } from "./fixture";
+export type {
+  AgentSessionFixture,
+  AgentSessionFixtureMeta,
+  AgentSessionFixtureRepo,
+  AgentSessionFixtureSummary,
+  FixtureAgentSessionEvent,
+  FixtureHighlightLayer,
+  FixtureLayerItem,
+} from "./fixture";

package/src/auxiliary/AuxiliaryManifestValidator.test.ts

@@ -0,0 +1,93 @@
+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

@@ -0,0 +1,132 @@
+/**
+ * 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

@@ -0,0 +1,18 @@
+/**
+ * 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';