@principal-ai/subsystems-core 0.29.0 → 0.30.0

package/src/types/resource-match.ts

@@ -1,263 +0,0 @@
-/**
- * Resource Matching Types
- *
- * Defines how logs are matched to canvas nodes based on OTEL resource attributes.
- * Supports multiple matching strategies: exact, glob, regex, existence, and oneOf.
- *
- * @example
- * ```yaml
- * # In canvas configuration
- * nodes:
- *   - id: "payment-service"
- *     resourceMatch:
- *       service.name: "payment-*"           # Glob pattern
- *       deployment.environment: "production" # Exact match
- *       db.system: { exists: true }         # Must have db.system attribute
- * ```
- */
-
-/**
- * Exact match operator
- *
- * @example
- * ```typescript
- * const match: ExactMatch = { exact: 'checkout-api' };
- * ```
- */
-export interface ExactMatch {
-  exact: string;
-}
-
-/**
- * Glob pattern match operator
- * Supports * (any characters) and ? (single character)
- *
- * @example
- * ```typescript
- * const match: GlobMatch = { glob: 'payment-*' };  // matches payment-service, payment-worker
- * const match2: GlobMatch = { glob: 'api-?' };     // matches api-1, api-2
- * ```
- */
-export interface GlobMatch {
-  glob: string;
-}
-
-/**
- * Regex pattern match operator
- *
- * @example
- * ```typescript
- * const match: RegexMatch = { regex: '^checkout-.+$' };
- * ```
- */
-export interface RegexMatch {
-  regex: string;
-}
-
-/**
- * Existence check operator
- *
- * @example
- * ```typescript
- * const mustExist: ExistsMatch = { exists: true };   // attribute must be present
- * const mustNotExist: ExistsMatch = { exists: false }; // attribute must be absent
- * ```
- */
-export interface ExistsMatch {
-  exists: boolean;
-}
-
-/**
- * OneOf match operator - matches any of the specified values
- *
- * @example
- * ```typescript
- * const match: OneOfMatch = { oneOf: ['production', 'staging'] };
- * ```
- */
-export interface OneOfMatch {
-  oneOf: string[];
-}
-
-/**
- * Match operator union type
- *
- * Can be one of the structured operators or a plain string (shorthand for exact match).
- *
- * @example
- * ```typescript
- * // These are equivalent:
- * const op1: MatchOperator = 'checkout-api';
- * const op2: MatchOperator = { exact: 'checkout-api' };
- *
- * // Other operators:
- * const glob: MatchOperator = { glob: 'payment-*' };
- * const regex: MatchOperator = { regex: '^api-.+$' };
- * const exists: MatchOperator = { exists: true };
- * const oneOf: MatchOperator = { oneOf: ['prod', 'staging'] };
- * ```
- */
-export type MatchOperator = ExactMatch | GlobMatch | RegexMatch | ExistsMatch | OneOfMatch | string;
-
-/**
- * Resource match criteria
- *
- * All specified conditions must match (AND logic).
- * Use for defining which logs should route to a specific node.
- *
- * @example
- * ```typescript
- * const match: ResourceMatch = {
- *   'service.name': 'checkout-api',              // Exact match (shorthand)
- *   'deployment.environment': 'production',      // Exact match (shorthand)
- *   'k8s.namespace.name': { glob: 'checkout-*' } // Glob pattern
- * };
- * ```
- */
-export interface ResourceMatch {
-  // Service identification (most common matching targets)
-  'service.name'?: MatchOperator;
-  'service.namespace'?: MatchOperator;
-  'service.instance.id'?: MatchOperator;
-  'service.version'?: MatchOperator;
-
-  // Deployment
-  'deployment.environment'?: MatchOperator;
-
-  // Kubernetes
-  'k8s.namespace.name'?: MatchOperator;
-  'k8s.deployment.name'?: MatchOperator;
-  'k8s.pod.name'?: MatchOperator;
-  'k8s.container.name'?: MatchOperator;
-  'k8s.node.name'?: MatchOperator;
-
-  // Database
-  'db.system'?: MatchOperator;
-  'db.name'?: MatchOperator;
-
-  // Host
-  'host.name'?: MatchOperator;
-  'host.id'?: MatchOperator;
-
-  // Cloud
-  'cloud.provider'?: MatchOperator;
-  'cloud.region'?: MatchOperator;
-
-  // Messaging
-  'messaging.system'?: MatchOperator;
-  'messaging.destination.name'?: MatchOperator;
-
-  // Allow arbitrary attribute matching
-  [key: string]: MatchOperator | undefined;
-}
-
-/**
- * Result of a match attempt
- *
- * Includes the match outcome, specificity score for priority resolution,
- * and details about which criteria matched or failed.
- */
-export interface MatchResult {
-  /** Whether all criteria matched */
-  matched: boolean;
-
-  /**
-   * Match specificity score (higher = more specific match)
-   *
-   * Scoring rules:
-   * - Each exact match: +10 points
-   * - Each oneOf match: +8 points
-   * - Each regex match: +5 points
-   * - Each glob match: +3 points
-   * - Each exists match: +1 point
-   *
-   * Used to resolve conflicts when multiple nodes match the same log.
-   */
-  score: number;
-
-  /** List of criteria keys that matched */
-  matchedCriteria: string[];
-
-  /** List of criteria keys that failed (for debugging) */
-  failedCriteria?: string[];
-}
-
-/**
- * Interface for nodes that support resource-based matching
- *
- * Nodes can have both resourceMatch (OTEL attributes) and sources (file paths).
- * When routing logs, resourceMatch takes priority over sources.
- */
-export interface ResourceMatchableNode {
-  /** Node identifier */
-  id: string;
-
-  /**
-   * Resource-based matching criteria (OTEL attributes)
-   * Takes priority over sources when both are specified.
-   */
-  resourceMatch?: ResourceMatch;
-
-  /**
-   * Path-based matching (source file globs)
-   * Used as fallback when resourceMatch is not specified or doesn't match.
-   * Also used for code coverage analysis.
-   */
-  sources?: string[];
-}
-
-// Type guards for match operators
-
-/**
- * Check if operator is an exact match
- */
-export function isExactMatch(op: MatchOperator): op is ExactMatch {
-  return typeof op === 'object' && 'exact' in op;
-}
-
-/**
- * Check if operator is a glob match
- */
-export function isGlobMatch(op: MatchOperator): op is GlobMatch {
-  return typeof op === 'object' && 'glob' in op;
-}
-
-/**
- * Check if operator is a regex match
- */
-export function isRegexMatch(op: MatchOperator): op is RegexMatch {
-  return typeof op === 'object' && 'regex' in op;
-}
-
-/**
- * Check if operator is an exists match
- */
-export function isExistsMatch(op: MatchOperator): op is ExistsMatch {
-  return typeof op === 'object' && 'exists' in op;
-}
-
-/**
- * Check if operator is a oneOf match
- */
-export function isOneOfMatch(op: MatchOperator): op is OneOfMatch {
-  return typeof op === 'object' && 'oneOf' in op;
-}
-
-/**
- * Check if operator is a string shorthand (exact match)
- */
-export function isStringShorthand(op: MatchOperator): op is string {
-  return typeof op === 'string';
-}
-
-/**
- * Normalize a match operator to its canonical form
- */
-export function normalizeOperator(
-  op: MatchOperator
-): ExactMatch | GlobMatch | RegexMatch | ExistsMatch | OneOfMatch {
-  if (typeof op === 'string') {
-    return { exact: op };
-  }
-  return op;
-}

package/src/types/version-registry.ts

@@ -1,150 +0,0 @@
-/**
- * Version Registry Types
- *
- * Defines the data structures for storing and retrieving versioned storyboard snapshots.
- * The version registry indexes storyboards by repository URL and commit SHA, allowing
- * traces to reference the exact workflow definitions that were active at the time of execution.
- */
-
-import type { DiscoveredStoryboard } from '../discovery/types';
-import type { ComponentLibrary, ResourceAttributes } from './library';
-
-/**
- * Version identifier combining repository URL and commit SHA
- */
-export interface VersionIdentifier {
-  /** Git repository URL (e.g., "https://github.com/org/repo") */
-  repositoryUrl: string;
-  /** Git commit SHA (full 40-character hash) */
-  commitSha: string;
-}
-
-/**
- * Complete snapshot of storyboards at a specific version
- *
- * This should be stored in the version registry when a version is built/deployed,
- * and retrieved when processing traces that reference this version.
- */
-export interface VersionSnapshot extends VersionIdentifier {
-  /**
-   * Complete storyboard definitions as discovered from the codebase at this version.
-   * Includes all metadata: canvas info, workflow paths, package names, etc.
-   */
-  storyboards: DiscoveredStoryboard[];
-
-  /**
-   * Library metadata from library.yaml
-   *
-   * Contains the library name, version, and description for identification.
-   */
-  library?: Pick<ComponentLibrary, 'version' | 'name' | 'description'>;
-
-  /**
-   * Resource definitions with owned-scopes for scope routing
-   *
-   * Maps resource identifiers to their OTEL resource attributes.
-   * The `owned-scopes` field in each resource is used to route
-   * instrumentation scopes to this snapshot's storyboards.
-   *
-   * @example
-   * ```yaml
-   * resources:
-   *   web-ade:
-   *     service.name: "web-ade"
-   *     owned-scopes:
-   *       - "auth-me"
-   *       - "@backlog-md/core"
-   * ```
-   */
-  resources?: Record<string, ResourceAttributes>;
-
-  /** When this version was registered */
-  registeredAt?: string;
-
-  /** Optional metadata about the build/deployment */
-  metadata?: {
-    /** Build/deployment environment (e.g., "production", "staging") */
-    environment?: string;
-    /** Branch name */
-    branch?: string;
-    /** Git tag if applicable */
-    tag?: string;
-    /** Additional custom metadata */
-    [key: string]: unknown;
-  };
-}
-
-/**
- * Request to register a new version in the registry
- */
-export interface RegisterVersionRequest {
-  /** Repository URL */
-  repositoryUrl: string;
-  /** Commit SHA */
-  commitSha: string;
-  /** Discovered storyboards from this version */
-  storyboards: DiscoveredStoryboard[];
-  /** Optional metadata */
-  metadata?: VersionSnapshot['metadata'];
-}
-
-/**
- * Response from querying the version registry
- */
-export interface GetVersionResponse {
-  /** Whether the version was found */
-  found: boolean;
-  /** Version snapshot if found */
-  snapshot?: VersionSnapshot;
-  /** Error message if not found or error occurred */
-  error?: string;
-}
-
-/**
- * Version registry interface
- *
- * Implementations might use:
- * - A database (PostgreSQL, MongoDB, etc.)
- * - A key-value store (Redis, DynamoDB)
- * - A file-based registry (S3, local filesystem)
- * - An in-memory cache for testing
- */
-export interface VersionRegistry {
-  /**
-   * Register a new version snapshot
-   * @param request - Version registration request
-   * @returns Promise that resolves when registered
-   */
-  register(request: RegisterVersionRequest): Promise<void>;
-
-  /**
-   * Get a version snapshot by repository URL and commit SHA
-   * @param repositoryUrl - Repository URL
-   * @param commitSha - Commit SHA
-   * @returns Promise with version snapshot if found
-   */
-  get(repositoryUrl: string, commitSha: string): Promise<GetVersionResponse>;
-
-  /**
-   * Check if a version exists in the registry
-   * @param repositoryUrl - Repository URL
-   * @param commitSha - Commit SHA
-   * @returns Promise with boolean indicating if version exists
-   */
-  exists(repositoryUrl: string, commitSha: string): Promise<boolean>;
-
-  /**
-   * Delete a version from the registry (for cleanup)
-   * @param repositoryUrl - Repository URL
-   * @param commitSha - Commit SHA
-   * @returns Promise that resolves when deleted
-   */
-  delete?(repositoryUrl: string, commitSha: string): Promise<void>;
-
-  /**
-   * List all versions for a repository (optional, for debugging/admin)
-   * @param repositoryUrl - Repository URL
-   * @returns Promise with array of version identifiers
-   */
-  listVersions?(repositoryUrl: string): Promise<VersionIdentifier[]>;
-}