@principal-ai/subsystems-core 0.29.0

package/dist/types/version-registry.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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[]>;
+}
+//# sourceMappingURL=version-registry.d.ts.map

package/dist/types/version-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-registry.d.ts","sourceRoot":"","sources":["../../src/types/version-registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAgB,SAAQ,iBAAiB;IACxD;;;OAGG;IACH,WAAW,EAAE,oBAAoB,EAAE,CAAC;IAEpC;;;;OAIG;IACH,OAAO,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,MAAM,GAAG,aAAa,CAAC,CAAC;IAErE;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAE/C,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,mDAAmD;IACnD,QAAQ,CAAC,EAAE;QACT,mEAAmE;QACnE,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,kBAAkB;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,4BAA4B;QAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,iCAAiC;QACjC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,qBAAqB;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,WAAW,EAAE,oBAAoB,EAAE,CAAC;IACpC,wBAAwB;IACxB,QAAQ,CAAC,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,oCAAoC;IACpC,KAAK,EAAE,OAAO,CAAC;IACf,gCAAgC;IAChC,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzD;;;;;OAKG;IACH,GAAG,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE3E;;;;;OAKG;IACH,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnE;;;;;OAKG;IACH,MAAM,CAAC,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjE;;;;OAIG;IACH,YAAY,CAAC,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;CACpE"}

package/dist/types/version-registry.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=version-registry.js.map

package/dist/types/version-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-registry.js","sourceRoot":"","sources":["../../src/types/version-registry.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}

package/dist/utils/CanvasConverter.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Canvas Converter
+ *
+ * Utilities for converting between Extended Canvas format and React Flow nodes/edges.
+ */
+import type { ExtendedCanvas, PVOtelExtension, PVEventSchema, PVBoundaryExtension } from '../types/canvas';
+import type { NodeState, EdgeState } from '../types';
+import type { ResourceMatch } from '../types/resource-match';
+/**
+ * React Flow node format
+ */
+export interface ReactFlowNode {
+    id: string;
+    type: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    data: {
+        name: string;
+        nodeType: string;
+        shape?: string;
+        icon?: string;
+        color?: string;
+        width?: number;
+        height?: number;
+        states?: Record<string, {
+            color?: string;
+            icon?: string;
+            label?: string;
+        }>;
+        sources?: string[];
+        references?: string[];
+        status?: 'draft' | 'approved' | 'implemented';
+        canvasType?: 'text' | 'file' | 'link' | 'group' | 'otel-event' | 'otel-span-convention' | 'otel-scope' | 'otel-resource' | 'otel-boundary';
+        text?: string;
+        file?: string;
+        url?: string;
+        description?: string;
+        otel?: PVOtelExtension;
+        resourceMatch?: ResourceMatch;
+        event?: PVEventSchema;
+        eventRef?: string;
+        events?: Record<string, PVEventSchema>;
+        boundary?: PVBoundaryExtension;
+        dataSchema?: Record<string, {
+            type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+            required?: boolean;
+            displayInLabel?: boolean;
+        }>;
+    };
+    style?: {
+        width?: number;
+        height?: number;
+    };
+}
+/**
+ * React Flow edge format
+ */
+export interface ReactFlowEdge {
+    id: string;
+    source: string;
+    target: string;
+    type?: string;
+    sourceHandle?: string;
+    targetHandle?: string;
+    label?: string;
+    data?: {
+        edgeType: string;
+        style?: string;
+        color?: string;
+        width?: number;
+        animation?: {
+            type: string;
+            duration?: number;
+            color?: string;
+        };
+    };
+    style?: {
+        stroke?: string;
+        strokeWidth?: number;
+        strokeDasharray?: string;
+    };
+    animated?: boolean;
+    markerEnd?: {
+        type: string;
+        color?: string;
+    };
+}
+/**
+ * Canvas Converter utility class
+ */
+export declare class CanvasConverter {
+    /**
+     * Convert Extended Canvas to React Flow nodes and edges
+     */
+    static canvasToReactFlow(canvas: ExtendedCanvas): {
+        nodes: ReactFlowNode[];
+        edges: ReactFlowEdge[];
+    };
+    /**
+     * Convert a single canvas node to React Flow node
+     */
+    private static convertNode;
+    /**
+     * Convert an OTEL node to React Flow node
+     * Note: OTEL event nodes (otel-event) do not support explicit fill/color fields.
+     * Event node colors are determined by scope (library.yaml) and injected by GraphRenderer.
+     * Other OTEL node types (scopes, spans, resources, boundaries) can use fill/color.
+     */
+    private static convertOtelNode;
+    /**
+     * Convert a standard JSON Canvas node to React Flow node
+     * Standard nodes (text/file/link/group) may use pv extensions
+     */
+    private static convertStandardNode;
+    /**
+     * Convert a single canvas edge to React Flow edge
+     */
+    private static convertEdge;
+    /**
+     * Convert Extended Canvas to internal NodeState/EdgeState format
+     */
+    static canvasToGraph(canvas: ExtendedCanvas): {
+        nodes: NodeState[];
+        edges: EdgeState[];
+    };
+    /**
+     * Convert an OTEL node to NodeState format
+     * Note: OTEL event nodes (otel-event) do not support explicit fill/color fields.
+     * Event node colors are determined by scope (library.yaml) and injected by GraphRenderer.
+     * Other OTEL node types (scopes, spans, resources, boundaries) can use fill/color.
+     */
+    private static convertOtelNodeToGraph;
+    /**
+     * Convert a standard JSON Canvas node to NodeState format
+     * Standard nodes may use pv extensions
+     */
+    private static convertStandardNodeToGraph;
+    /**
+     * Convert React Flow nodes/edges back to Extended Canvas format
+     */
+    static reactFlowToCanvas(nodes: ReactFlowNode[], edges: ReactFlowEdge[], metadata?: {
+        name?: string;
+        description?: string;
+    }): ExtendedCanvas;
+}
+//# sourceMappingURL=CanvasConverter.d.ts.map

package/dist/utils/CanvasConverter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CanvasConverter.d.ts","sourceRoot":"","sources":["../../src/utils/CanvasConverter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,cAAc,EAad,eAAe,EACf,aAAa,EACb,mBAAmB,EAEpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnC,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC3E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,MAAM,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,aAAa,CAAC;QAE9C,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,YAAY,GAAG,sBAAsB,GAAG,YAAY,GAAG,eAAe,GAAG,eAAe,CAAC;QAC3I,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,eAAe,CAAC;QACvB,aAAa,CAAC,EAAE,aAAa,CAAC;QAC9B,KAAK,CAAC,EAAE,aAAa,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;QACvC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;QAC/B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;YAC1B,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;YAC3D,QAAQ,CAAC,EAAE,OAAO,CAAC;YACnB,cAAc,CAAC,EAAE,OAAO,CAAC;SAC1B,CAAC,CAAC;KACJ,CAAC;IACF,KAAK,CAAC,EAAE;QACN,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE;QACL,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE;YACV,IAAI,EAAE,MAAM,CAAC;YACb,QAAQ,CAAC,EAAE,MAAM,CAAC;YAClB,KAAK,CAAC,EAAE,MAAM,CAAC;SAChB,CAAC;KAEH,CAAC;IACF,KAAK,CAAC,EAAE;QACN,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE;QACV,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAyBD;;GAEG;AACH,qBAAa,eAAe;IAC1B;;OAEG;IACH,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG;QAChD,KAAK,EAAE,aAAa,EAAE,CAAC;QACvB,KAAK,EAAE,aAAa,EAAE,CAAC;KACxB;IAqBD;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAU1B;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAqD9B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAiElC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IA2C1B;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG;QAC5C,KAAK,EAAE,SAAS,EAAE,CAAC;QACnB,KAAK,EAAE,SAAS,EAAE,CAAC;KACpB;IA4DD;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;IA4DrC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,0BAA0B;IAsEzC;;OAEG;IACH,MAAM,CAAC,iBAAiB,CACtB,KAAK,EAAE,aAAa,EAAE,EACtB,KAAK,EAAE,aAAa,EAAE,EACtB,QAAQ,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GACjD,cAAc;CA2GlB"}