@principal-ai/subsystems-core 0.29.0 → 0.31.0

package/dist/types/canvas.d.ts

@@ -1,1138 +0,0 @@
-/**
- * JSON Canvas Extended Types
- *
- * This module defines types that extend the JSON Canvas spec (https://jsoncanvas.org/spec/1.0/)
- * with Principal View Framework extensions.
- *
- * Design principle: Extensions use top-level fields where possible (name, markdown, edgeType)
- * for simplicity. Node-level extensions use a `pv` field for complex metadata.
- *
- * DEPRECATION: Canvas-level `pv` field and edge-level `pv` field are deprecated.
- * Use top-level `name`, `markdown` fields on canvas, and `edgeType` field on edges.
- *
- * This allows:
- * 1. Authoring layouts visually in Obsidian or other canvas tools
- * 2. Rendering with rich animations and states in React Flow
- * 3. Round-trip editing without data loss
- */
-import type { CanvasScope, CanvasAuditConfig } from './canvas-scope';
-import type { ResourceMatch } from './resource-match';
-import type { JsonValue } from './index';
-/**
- * Canvas color - either a hex string or preset number (1-6)
- * Presets: 1=red, 2=orange, 3=yellow, 4=green, 5=cyan, 6=purple
- *
- * Note: Obsidian Canvas saves numeric presets as strings ("1"-"6"),
- * so we accept both number and string formats.
- */
-export type CanvasColor = string | 1 | 2 | 3 | 4 | 5 | 6;
-/**
- * Side of a node for edge connections
- */
-export type CanvasSide = 'top' | 'right' | 'bottom' | 'left';
-/**
- * Edge endpoint shape
- */
-export type CanvasEndpoint = 'none' | 'arrow';
-/**
- * Background style for group nodes
- */
-export type CanvasBackgroundStyle = 'cover' | 'ratio' | 'repeat';
-/**
- * Base node properties (common to all node types)
- */
-export interface CanvasNodeBase {
-    /** Unique identifier */
-    id: string;
-    /** X position in pixels */
-    x: number;
-    /** Y position in pixels */
-    y: number;
-    /** Width in pixels */
-    width: number;
-    /** Height in pixels */
-    height: number;
-    /** Optional color */
-    color?: CanvasColor;
-}
-/**
- * Text node - stores plain text or markdown
- */
-export interface CanvasTextNode extends CanvasNodeBase {
-    type: 'text';
-    /** Markdown-formatted text content */
-    text: string;
-}
-/**
- * File node - references an external file
- */
-export interface CanvasFileNode extends CanvasNodeBase {
-    type: 'file';
-    /** Path to the file */
-    file: string;
-    /** Optional subpath (heading or block link) */
-    subpath?: string;
-}
-/**
- * Link node - references a URL
- */
-export interface CanvasLinkNode extends CanvasNodeBase {
-    type: 'link';
-    /** URL to link to */
-    url: string;
-}
-/**
- * Group node - visual container for other nodes
- */
-export interface CanvasGroupNode extends CanvasNodeBase {
-    type: 'group';
-    /** Optional label for the group */
-    label?: string;
-    /** Optional background image path */
-    background?: string;
-    /** Background image style */
-    backgroundStyle?: CanvasBackgroundStyle;
-}
-/**
- * Union of all standard canvas node types
- */
-export type CanvasNode = CanvasTextNode | CanvasFileNode | CanvasLinkNode | CanvasGroupNode;
-/**
- * Canvas edge connecting two nodes
- */
-export interface CanvasEdge {
-    /** Unique identifier */
-    id: string;
-    /** Source node ID */
-    fromNode: string;
-    /** Target node ID */
-    toNode: string;
-    /** Side of source node */
-    fromSide?: CanvasSide;
-    /** Side of target node */
-    toSide?: CanvasSide;
-    /** Endpoint shape at source (default: 'none') */
-    fromEnd?: CanvasEndpoint;
-    /** Endpoint shape at target (default: 'arrow') */
-    toEnd?: CanvasEndpoint;
-    /** Edge color */
-    color?: CanvasColor;
-    /** Edge label */
-    label?: string;
-}
-/**
- * Standard JSON Canvas document
- */
-export interface Canvas {
-    /** Array of nodes (ordered by z-index ascending) */
-    nodes?: CanvasNode[];
-    /** Array of edges */
-    edges?: CanvasEdge[];
-}
-/**
- * Animation types for edges
- */
-export type PVAnimationType = 'flow' | 'pulse' | 'particle' | 'glow';
-/**
- * Animation direction
- */
-export type PVAnimationDirection = 'forward' | 'backward' | 'bidirectional';
-/**
- * Node shape for rendering
- */
-export type PVNodeShape = 'circle' | 'rectangle' | 'hexagon' | 'diamond' | 'custom';
-/**
- * Edge line style
- */
-export type PVEdgeStyle = 'solid' | 'dashed' | 'dotted' | 'animated';
-/**
- * Log level for path-based association
- */
-export type PVLogLevel = 'debug' | 'info' | 'warn' | 'error';
-/**
- * State definition for a node
- */
-export interface PVNodeState {
-    /** Color when in this state */
-    color?: string;
-    /** Icon when in this state */
-    icon?: string;
-    /** Display label */
-    label?: string;
-}
-/**
- * OTEL node classification
- *
- * @deprecated Use `pv.nodeType` instead. Will be removed in a future version.
- * For example, use `nodeType: "scope"` instead of `otel.kind: "type"`.
- */
-export type PVOtelKind = 'type' | 'service' | 'instance';
-/**
- * OTEL category for type nodes
- *
- * @deprecated Use `pv.nodeType` instead. Will be removed in a future version.
- * For example, use `nodeType: "span-convention"` instead of `otel.category: "span"`.
- */
-export type PVOtelCategory = 'log' | 'resource' | 'span' | 'scope' | 'match' | 'audit' | 'config' | 'router' | 'collector';
-/**
- * OTel SpanKind values for span conventions
- *
- * Describes the relationship between a span and its remote parent/children.
- * Standard OTel concept - these values are fixed by the OTel spec.
- *
- * @see https://opentelemetry.io/docs/specs/otel/trace/api/#spankind
- */
-export type PVOtelSpanKind = 'UNSPECIFIED' | 'INTERNAL' | 'SERVER' | 'CLIENT' | 'PRODUCER' | 'CONSUMER';
-import type { OtelSpanKind } from './otel';
-/**
- * OTEL span matching criteria
- *
- * Defines rules for matching incoming OTEL spans to this canvas node.
- * Multiple criteria are combined with AND logic (all must match).
- */
-export interface PVOtelSpanMatch {
-    /**
-     * Match span name
-     *
-     * Supports:
-     * - Exact string: "validateUser"
-     * - Array of options: ["GET /api/users", "POST /api/users"]
-     * - Glob patterns: "GET /api/*", "*.checkout"
-     *
-     * @example "validateUser"
-     * @example ["GET /api/users", "POST /api/users"]
-     * @example "*.checkout"
-     */
-    name?: string | string[];
-    /**
-     * Match span kind
-     *
-     * @example "SPAN_KIND_SERVER"
-     * @example "SPAN_KIND_CLIENT"
-     */
-    kind?: OtelSpanKind | OtelSpanKind[];
-    /**
-     * Match span attributes
-     *
-     * All specified attributes must match (AND logic).
-     * Supports exact values and wildcards.
-     *
-     * @example
-     * {
-     *   "http.route": "/api/checkout",
-     *   "http.method": "POST"
-     * }
-     *
-     * @example
-     * {
-     *   "db.system": "postgresql",
-     *   "db.operation": "*"  // Any operation
-     * }
-     */
-    attributes?: Record<string, string | string[]>;
-    /**
-     * Match span events
-     *
-     * If specified, span must contain at least one event matching these criteria.
-     *
-     * @example
-     * {
-     *   name: "exception",
-     *   attributes: { "exception.type": "ValidationError" }
-     * }
-     */
-    event?: {
-        name?: string | string[];
-        attributes?: Record<string, string | string[]>;
-    };
-}
-/**
- * OTEL resource matching criteria
- *
- * Matches against OTEL resource attributes (service.name, deployment.environment, etc.).
- * Multiple attributes are combined with AND logic.
- */
-export interface PVOtelResourceMatch {
-    /**
-     * Resource attribute patterns to match
-     *
-     * Supports:
-     * - Exact match: { "service.name": "checkout-api" }
-     * - Wildcard: { "service.name": "*-api" }
-     * - Array of options: { "service.name": ["api-1", "api-2"] }
-     *
-     * @example
-     * {
-     *   "service.name": "checkout-service",
-     *   "deployment.environment": "production"
-     * }
-     */
-    [attributeKey: string]: string | string[];
-}
-/**
- * OTEL-specific node extension
- *
- * Used to mark nodes as representing OTEL concepts in architectural diagrams
- * and to define runtime span matching criteria.
- */
-export interface PVOtelExtension {
-    /**
-     * Kind of OTEL node
-     * - `type`: Represents a TypeScript type/interface (e.g., OtelLog, ResourceMatch)
-     * - `service`: Represents a runtime service (e.g., LogRouter, AuditCollector)
-     * - `instance`: Represents an actual runtime instance (e.g., a specific pod)
-     *
-     * @deprecated Use `pv.nodeType` instead. Will be removed in a future version.
-     */
-    kind?: PVOtelKind;
-    /**
-     * Category within OTEL domain
-     *
-     * @deprecated Use `pv.nodeType` instead. Will be removed in a future version.
-     */
-    category?: PVOtelCategory;
-    /**
-     * Span pattern for span convention nodes
-     *
-     * Defines the naming pattern for spans that match this convention.
-     * Supports wildcards (e.g., "validate.*", "task.create").
-     *
-     * Used in architecture.spans.canvas to define the vocabulary of operations.
-     *
-     * @example "validate.*"
-     * @example "task.create"
-     * @example "http.request"
-     */
-    spanPattern?: string;
-    /**
-     * OTel SpanKind for span convention nodes
-     *
-     * Specifies what kind of span this convention represents.
-     * Implementers should use this when creating spans.
-     *
-     * @example "SERVER" - for entry points handling incoming requests
-     * @example "INTERNAL" - for internal operations
-     * @example "CLIENT" - for outgoing calls to external services
-     */
-    spanKind?: PVOtelSpanKind;
-    /**
-     * Resource matching criteria
-     *
-     * When specified, this node will highlight when spans are received
-     * from resources with matching attributes.
-     */
-    resourceMatch?: PVOtelResourceMatch;
-    /**
-     * Span matching criteria
-     *
-     * When specified, this node will highlight when spans matching
-     * these criteria are received.
-     */
-    spanMatch?: PVOtelSpanMatch;
-    /**
-     * Files where this event is instrumented
-     *
-     * Specifies the exact file paths where this OTEL event should be emitted.
-     * Used by coverage tools to validate that events are properly instrumented.
-     *
-     * @example ["src/app/api/auth/callback/route.ts"]
-     */
-    files?: string[];
-    /**
-     * Instrumentation scope that emits this event
-     *
-     * Identifies which tracer/instrumentation library creates this span or event.
-     * Maps to `getTracer('scope-name')` in the instrumented code.
-     *
-     * Required when the parent node's status is 'approved' or 'implemented'.
-     * Should match an entry in the library.yaml `owned-scopes` list.
-     *
-     * @example "terminal-activity"
-     * @example "auth"
-     * @example "quality-panel"
-     */
-    scope?: string;
-    /** Allow additional properties */
-    [key: string]: JsonValue | PVOtelResourceMatch | PVOtelSpanMatch | string[] | undefined;
-}
-/**
- * Event field schema definition
- */
-export interface PVEventFieldSchema {
-    /** Field data type */
-    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
-    /** Whether this field is required */
-    required?: boolean;
-    /** Description of what this field represents */
-    description?: string;
-    /**
-     * Whether this attribute is intended for template display.
-     * Set to false for telemetry/analytics-only attributes.
-     * Defaults to true.
-     */
-    display?: boolean;
-}
-/**
- * Event schema definition for a specific event type
- */
-export interface PVEventSchema {
-    /** Event name (e.g., 'conversion.started', 'user.login') */
-    name: string;
-    /** Description of what this event represents */
-    description: string;
-    /** Expected attributes/fields for this event */
-    attributes: Record<string, PVEventFieldSchema>;
-}
-/**
- * Node implementation status
- *
- * Tracks the lifecycle of a node from design to implementation.
- */
-export type PVNodeStatus = 'draft' | 'approved' | 'implemented';
-/**
- * Direction of boundary interaction
- */
-export type PVBoundaryDirection = 'outbound' | 'inbound';
-/**
- * Node query criteria for boundary resolution
- *
- * Defines what the corresponding node looks like in the external system's traces.
- * Used for cross-repo resolution and live trace correlation.
- */
-export interface PVBoundaryNodeQuery {
-    /** Event name to match in external system */
-    'pv.event.name'?: string;
-    /** Event namespace to match */
-    'pv.event.namespace'?: string;
-    /** Additional attribute matches */
-    [key: string]: string | undefined;
-}
-/**
- * Boundary extension for nodes representing external system interfaces
- *
- * Boundaries define interaction points where control crosses system edges.
- * The `node` field specifies what the corresponding node looks like in the
- * external system, enabling cross-repo resolution and trace correlation.
- *
- * @example Outbound host callback
- * ```typescript
- * boundary: {
- *   direction: 'outbound',
- *   node: {
- *     'pv.event.name': 'host.batch-layout-initialized',
- *     'pv.event.namespace': 'collection-host'
- *   }
- * }
- * ```
- *
- * @example Inbound webhook
- * ```typescript
- * boundary: {
- *   direction: 'inbound',
- *   node: {
- *     'pv.event.name': 'webhook.repository-created',
- *     'pv.event.namespace': 'github'
- *   }
- * }
- * ```
- */
-export interface PVBoundaryExtension {
-    /**
-     * Direction of the boundary interaction
-     *
-     * - `outbound`: This system calls out to external system
-     * - `inbound`: External system calls into this system
-     */
-    direction: PVBoundaryDirection;
-    /**
-     * Node query for resolving the corresponding node in external system
-     *
-     * Specifies the expected shape of the matching node for registry lookup
-     * and live trace correlation.
-     */
-    node: PVBoundaryNodeQuery;
-}
-/**
- * Principal View node extensions
- */
-export interface PVNodeExtension {
-    /** Custom node type identifier */
-    nodeType: string;
-    /**
-     * Display name for this node
-     *
-     * Preferred over parsing the `text` field. Use this for the node label.
-     */
-    name?: string;
-    /**
-     * Description of what this node represents
-     *
-     * Shown in tooltips or detail panels.
-     */
-    description?: string;
-    /**
-     * Implementation status of this node
-     *
-     * - `draft`: Design/proposal phase (requires pv.otel.files if known, otherwise pv.references)
-     * - `approved`: Design finalized, ready for implementation (requires pv.otel.files)
-     * - `implemented`: Code exists with instrumentation (requires pv.otel.files and events in code)
-     *
-     * Used by coverage tools to determine validation requirements and coverage tracking.
-     */
-    status?: PVNodeStatus;
-    /**
-     * OTEL-specific metadata
-     *
-     * Used when this node represents an OTEL concept (type, service, or instance).
-     */
-    otel?: PVOtelExtension;
-    /** Visual shape */
-    shape?: PVNodeShape;
-    /** Icon identifier (Lucide icons) */
-    icon?: string;
-    /** Fill color (hex string) - takes priority over node.color */
-    fill?: string;
-    /** Stroke/border color (hex string) */
-    stroke?: string;
-    /** State definitions */
-    states?: Record<string, PVNodeState>;
-    /**
-     * Origin of the code this node represents
-     *
-     * - `internal` (default): Code exists in this repository, file paths in `pv.otel.files` will be validated
-     * - `external`: Code exists in external packages/libraries, file existence validation is skipped
-     *
-     * Use `external` for:
-     * - npm dependencies (e.g., `@logfire/pydantic-ai`)
-     * - Auto-instrumented events from observability libraries
-     * - Third-party APIs or services
-     * - Cross-repository references
-     *
-     * When `origin: "external"`, the `references` field is required to document
-     * what external package or service this node represents.
-     *
-     * @example "external"
-     */
-    origin?: 'internal' | 'external';
-    /**
-     * Auxiliary references and related documentation
-     *
-     * Use for documenting related packages, external dependencies, or supplementary notes.
-     * Required when `origin: "external"` to document what external package/service this represents.
-     *
-     * @example ["@logfire/pydantic-ai"] // external package reference
-     * @example ["https://docs.pydantic.dev/logfire/"] // documentation link
-     */
-    references?: string[];
-    /**
-     * @deprecated Use `references` instead. Will be removed in a future version.
-     */
-    sources?: string[];
-    /**
-     * Resource-based matching for OTEL logs
-     *
-     * When specified, logs with matching OTEL resource attributes
-     * will be routed to this node. Takes priority over sources.
-     *
-     * @example
-     * ```typescript
-     * resourceMatch: {
-     *   'service.name': 'checkout-api',
-     *   'deployment.environment': 'production'
-     * }
-     * ```
-     */
-    resourceMatch?: ResourceMatch;
-    /**
-     * Event schema for type-safe telemetry validation (inline definition)
-     *
-     * Defines the single event that this node emits during execution.
-     * Used for compile-time and runtime validation of telemetry events.
-     * Each node should emit exactly one event type.
-     *
-     * Use this for one-off events specific to this node.
-     * For reusable events, use `eventRef` to reference library event schemas.
-     *
-     * @example
-     * ```typescript
-     * event: {
-     *   name: 'conversion.started',
-     *   description: 'Graph conversion begins',
-     *   attributes: {
-     *     'config.nodeTypes': { type: 'number', required: true },
-     *     'config.edgeTypes': { type: 'number', required: true }
-     *   }
-     * }
-     * ```
-     */
-    event?: PVEventSchema;
-    /**
-     * Reference to a library event schema
-     *
-     * References an event schema defined in library.yaml's `eventSchemas` section.
-     * This promotes reusability and consistency across canvases.
-     *
-     * NOTE: A node cannot have both `event` and `eventRef` - choose one.
-     * Validators will flag nodes that have both as an error.
-     *
-     * @example
-     * ```typescript
-     * eventRef: 'auth.callback.started'
-     * ```
-     */
-    eventRef?: string;
-    /** Data schema for typed fields */
-    dataSchema?: Record<string, {
-        type: 'string' | 'number' | 'boolean' | 'object' | 'array';
-        required?: boolean;
-        displayInLabel?: boolean;
-        /**
-         * Human-readable description of what this field represents.
-         * Required in .otel.canvas files (enforced by validator).
-         */
-        description?: string;
-        /**
-         * Example value for UI previews, mock traces, and testing.
-         * Required in .otel.canvas files (enforced by validator).
-         */
-        placeholder?: unknown;
-    }>;
-    /** Layout hints */
-    layout?: {
-        layer?: number;
-        cluster?: string;
-    };
-    /**
-     * Boundary extension for nodes representing external system interfaces
-     *
-     * When `nodeType` is `"boundary"`, this field defines the boundary details.
-     * Boundary nodes represent interface points where control crosses system edges.
-     * The `node` field specifies what the corresponding node looks like in the
-     * external system, enabling cross-repo resolution and trace correlation.
-     *
-     * When a node has `nodeType: "boundary"`, it does NOT require `event` or `eventRef`
-     * fields since the boundary is external and doesn't emit telemetry from our code.
-     *
-     * @example
-     * ```typescript
-     * {
-     *   nodeType: "boundary",
-     *   boundary: {
-     *     direction: "outbound",
-     *     node: {
-     *       "pv.event.name": "host.batch-layout-initialized",
-     *       "pv.event.namespace": "collection-host"
-     *     }
-     *   }
-     * }
-     * ```
-     */
-    boundary?: PVBoundaryExtension;
-}
-/**
- * Principal View edge extensions
- */
-export interface PVEdgeExtension {
-    /** Custom edge type identifier */
-    edgeType: string;
-    /** Line style */
-    style?: PVEdgeStyle;
-    /** Line width in pixels */
-    width?: number;
-    /** Default animation */
-    animation?: {
-        type: PVAnimationType;
-        duration?: number;
-        color?: string;
-    };
-}
-/**
- * Path-based configuration options
- */
-export interface PVPathConfig {
-    /** Project root for path normalization */
-    projectRoot?: string;
-    /** Enable source capture from stack traces */
-    captureSource?: boolean;
-    /** Enable action pattern matching */
-    enableActionPatterns?: boolean;
-    /** Minimum log level to process */
-    logLevel?: PVLogLevel;
-    /** Ignore logs without source info */
-    ignoreUnsourced?: boolean;
-}
-/**
- * Display configuration
- */
-export interface PVDisplayConfig {
-    /** Layout algorithm (manual uses canvas positions) */
-    layout?: 'hierarchical' | 'force-directed' | 'circular' | 'manual';
-    /** Color theme */
-    theme?: {
-        primary?: string;
-        success?: string;
-        warning?: string;
-        danger?: string;
-        info?: string;
-    };
-    /** Animation settings */
-    animations?: {
-        enabled?: boolean;
-        speed?: number;
-    };
-}
-/**
- * Node type definition (stored at canvas level in pv.nodeTypes)
- */
-export interface PVNodeTypeDefinition {
-    /** Display label */
-    label?: string;
-    /** Description of this node type (required) */
-    description: string;
-    /** Fill color (hex string) */
-    color?: string;
-    /** Icon identifier (Lucide icons) */
-    icon?: string;
-    /** Visual shape */
-    shape?: PVNodeShape;
-}
-/**
- * Edge type definition (stored at canvas level)
- */
-export interface PVEdgeTypeDefinition {
-    /** Display label */
-    label?: string;
-    /** Line style */
-    style?: PVEdgeStyle;
-    /** Line color */
-    color?: string;
-    /** Line width */
-    width?: number;
-    /** Whether edge is directed */
-    directed?: boolean;
-    /** Default animation */
-    animation?: {
-        type: PVAnimationType;
-        duration?: number;
-        color?: string;
-    };
-    /** Label configuration (for dynamic labels) */
-    labelConfig?: {
-        field?: string;
-        position?: 'start' | 'middle' | 'end';
-    };
-}
-/**
- * Canvas-level Principal View extensions
- *
- * @deprecated The `pv` field is fully deprecated. All fields have been moved to top-level.
- * This interface will be removed in a future version.
- *
- * Migration - move all fields to top-level:
- * - `pv.name` → `name`
- * - `pv.markdown` → `markdown`
- * - `pv.description` → `description`
- * - `pv.nodeTypes` → `nodeTypes`
- * - `pv.edgeTypes` → `edgeTypes`
- * - `pv.display` → `display`
- * - `pv.pathConfig` → `pathConfig`
- * - `pv.scope` → `scope`
- * - `pv.audit` → `audit`
- * - `pv.version` → removed (not used)
- */
-export interface PVCanvasExtension {
-    /** @deprecated Use top-level `name` field instead */
-    name?: string;
-    /** @deprecated Use top-level `description` field instead */
-    description?: string;
-    /** @deprecated Use top-level `markdown` field instead */
-    markdown?: string;
-    /** @deprecated Use top-level `nodeTypes` field instead */
-    nodeTypes?: Record<string, PVNodeTypeDefinition>;
-    /** @deprecated Use top-level `edgeTypes` field instead */
-    edgeTypes?: Record<string, PVEdgeTypeDefinition>;
-    /** @deprecated Use top-level `pathConfig` field instead */
-    pathConfig?: PVPathConfig;
-    /** @deprecated Use top-level `display` field instead */
-    display?: PVDisplayConfig;
-    /** @deprecated Use top-level `scope` field instead */
-    scope?: CanvasScope;
-    /** @deprecated Use top-level `audit` field instead */
-    audit?: CanvasAuditConfig;
-}
-/**
- * Extended text node with PV extensions
- */
-export interface ExtendedCanvasTextNode extends CanvasTextNode {
-    pv?: PVNodeExtension;
-}
-/**
- * Extended file node with PV extensions
- */
-export interface ExtendedCanvasFileNode extends CanvasFileNode {
-    pv?: PVNodeExtension;
-}
-/**
- * Extended link node with PV extensions
- */
-export interface ExtendedCanvasLinkNode extends CanvasLinkNode {
-    pv?: PVNodeExtension;
-}
-/**
- * Extended group node with PV extensions
- */
-export interface ExtendedCanvasGroupNode extends CanvasGroupNode {
-    pv?: PVNodeExtension;
-}
-/**
- * Base interface for all OTEL node types
- *
- * These are custom node types that extend JSON Canvas for OpenTelemetry concepts.
- * Standard canvas tools will not recognize these types.
- */
-export interface OtelNodeBase extends CanvasNodeBase {
-    /** Display label shown on canvas node (required) */
-    label: string;
-    /** Icon identifier (Lucide icons) */
-    icon?: string;
-    /** Fill color (hex string) */
-    fill?: string;
-    /** Stroke/border color (hex string) */
-    stroke?: string;
-    /** Visual shape */
-    shape?: PVNodeShape;
-}
-/**
- * Shared OTEL instrumentation metadata
- *
- * Common fields for tracking implementation status and code location.
- */
-export interface OtelMetadata {
-    /** Implementation status */
-    status?: PVNodeStatus;
-    /** Instrumentation scope (maps to getTracer('scope-name')) */
-    scope?: string;
-    /** Files where this is instrumented */
-    files?: string[];
-    /**
-     * Origin of the code
-     * - 'internal': Code exists in this repository (default)
-     * - 'external': Code exists in external packages/libraries
-     */
-    origin?: 'internal' | 'external';
-    /** References/documentation for external code */
-    references?: string[];
-}
-/**
- * OTEL Event Node
- *
- * Represents a telemetry event emitted during workflow execution.
- * The event schema defines the structure of the telemetry data.
- */
-/**
- * OTEL Event Node - represents a telemetry event
- *
- * @remarks
- * IMPORTANT: Event nodes should NOT use fill or color fields.
- * Event nodes use scope-based coloring exclusively for consistency.
- * Set the scope in otel.scope and define scope colors in library.yaml.
- * Using fill or color fields will cause validation errors.
- */
-export interface OtelEventNode extends OtelNodeBase {
-    type: 'otel-event';
-    /** Inline event schema definition */
-    event?: PVEventSchema;
-    /** Reference to a library event schema */
-    eventRef?: string;
-    /** Data schema for typed fields in templates */
-    dataSchema?: Record<string, {
-        type: 'string' | 'number' | 'boolean' | 'object' | 'array';
-        required?: boolean;
-        description?: string;
-        placeholder?: unknown;
-    }>;
-    /** OTEL instrumentation metadata */
-    otel?: OtelMetadata;
-}
-/**
- * Workflow chip displayed on span convention nodes
- * Shows which workflow.json scenarios reference this span
- */
-export interface WorkflowChip {
-    /** Workflow scenario ID for selection/filtering */
-    id: string;
-    /** Display label (may be truncated) */
-    label: string;
-    /** Optional color for the chip */
-    color?: string;
-}
-/**
- * OTEL Span Convention Node
- *
- * Defines a span naming convention/pattern for consistent instrumentation.
- */
-export interface OtelSpanConventionNode extends OtelNodeBase {
-    type: 'otel-span-convention';
-    /** Short description of this span convention */
-    description?: string;
-    /** OTEL metadata including span-specific fields */
-    otel: OtelMetadata & {
-        /** Span naming pattern (e.g., "validate.*", "http.request") */
-        spanPattern: string;
-        /** OTel SpanKind */
-        spanKind?: PVOtelSpanKind;
-        /** Span matching criteria for runtime correlation */
-        spanMatch?: PVOtelSpanMatch;
-    };
-    /** Workflow chips showing which workflow.json scenarios use this span */
-    workflowChips?: WorkflowChip[];
-}
-/**
- * OTEL Scope Node
- *
- * Represents an instrumentation scope (tracer instance).
- */
-export interface OtelScopeNode extends OtelNodeBase {
-    type: 'otel-scope';
-    /** Short description of this instrumentation scope */
-    description?: string;
-    /**
-     * Optional source paths that define this scope's code region.
-     * Each entry may be a folder (covers all descendants) or a specific file.
-     * When present, events under this scope may only originate from files
-     * covered by one of these paths, and every `event-namespace` declared in
-     * this scope's events canvas must have its own `paths` nested inside this
-     * region. Scopes without `paths` remain unenforced — enforcement is opt-in
-     * per scope.
-     *
-     * Semantics are "ownership / partition", distinct from `otel.files` on
-     * `otel-event` nodes (which lists specific emission sites). Across scopes,
-     * paths must be disjoint except for strict parent-child nesting by
-     * dotted-scope name (longest-prefix wins).
-     */
-    paths?: string[];
-    /** OTEL metadata - scope name is required */
-    otel: OtelMetadata & {
-        /** Scope name (required - maps to getTracer('scope-name')) */
-        scope: string;
-    };
-}
-/**
- * OTEL Resource Node
- *
- * Represents a service or deployment resource identified by OTEL resource attributes.
- */
-export interface OtelResourceNode extends OtelNodeBase {
-    type: 'otel-resource';
-    /** Short description of this resource */
-    description?: string;
-    /** OTEL metadata including resource matching criteria */
-    otel: OtelMetadata & {
-        /** Resource attribute matching criteria */
-        resourceMatch: PVOtelResourceMatch;
-    };
-}
-/**
- * OTEL Boundary Node
- *
- * Represents an interface point with an external system.
- */
-export interface OtelBoundaryNode extends OtelNodeBase {
-    type: 'otel-boundary';
-    /** Short description of this boundary */
-    description?: string;
-    /** OTEL instrumentation metadata */
-    otel?: OtelMetadata;
-    /** Boundary configuration (required) */
-    boundary: PVBoundaryExtension;
-}
-/**
- * Union of all OTEL node types
- */
-export type OtelNode = OtelEventNode | OtelSpanConventionNode | OtelScopeNode | OtelResourceNode | OtelBoundaryNode;
-/**
- * Union of all extended node types (JSON Canvas + OTEL extensions)
- */
-export type ExtendedCanvasNode = ExtendedCanvasTextNode | ExtendedCanvasFileNode | ExtendedCanvasLinkNode | ExtendedCanvasGroupNode | OtelEventNode | OtelSpanConventionNode | OtelScopeNode | OtelResourceNode | OtelBoundaryNode;
-/**
- * Extended edge with PV extensions
- */
-export interface ExtendedCanvasEdge extends CanvasEdge {
-    /**
-     * Custom edge type identifier
-     *
-     * Used to categorize edges (e.g., "data-flow", "control-flow", "dependency").
-     * Replaces the deprecated `pv.edgeType` field.
-     *
-     * @example "data-flow"
-     * @example "control-flow"
-     */
-    edgeType?: string;
-    /**
-     * @deprecated Use top-level `edgeType` field instead.
-     * Validation will error if this field is present.
-     *
-     * Migration:
-     * ```json
-     * // Before (deprecated):
-     * { "id": "e1", "fromNode": "a", "toNode": "b", "pv": { "edgeType": "data-flow" } }
-     *
-     * // After:
-     * { "id": "e1", "fromNode": "a", "toNode": "b", "edgeType": "data-flow" }
-     * ```
-     */
-    pv?: PVEdgeExtension;
-}
-/**
- * Extended Canvas document with Principal View support
- *
- * This is the primary type for .canvas files used with the Principal View Framework.
- * It supports both standard JSON Canvas node types (text, file, link, group) and
- * custom OTEL node types (otel-event, otel-span-convention, etc.).
- *
- * Standard canvas tools will only recognize the JSON Canvas node types.
- */
-export interface ExtendedCanvas {
-    /**
-     * Canvas display name
-     *
-     * Human-readable name for this canvas, shown in UIs and listings.
-     *
-     * @example "Service Resources"
-     * @example "Checkout Flow"
-     */
-    name?: string;
-    /**
-     * Associated markdown documentation file
-     *
-     * Path to a markdown file that documents this canvas.
-     * For .otel.canvas files, this field is required.
-     * The path must be relative to the git repository root.
-     *
-     * Convention: If not specified, defaults to same basename as canvas file.
-     * e.g., `resources.canvas` → `resources.md`
-     *
-     * @example ".principal-views/resources.md"
-     * @example "docs/architecture/checkout-flow.md"
-     */
-    markdown?: string;
-    /** Canvas description */
-    description?: string;
-    /** Node type definitions (shared across nodes) */
-    nodeTypes?: Record<string, PVNodeTypeDefinition>;
-    /** Edge type definitions (shared across edges) */
-    edgeTypes?: Record<string, PVEdgeTypeDefinition>;
-    /** Path-based configuration */
-    pathConfig?: PVPathConfig;
-    /** Display configuration */
-    display?: PVDisplayConfig;
-    /**
-     * Canvas scope for log filtering
-     *
-     * Only logs matching this scope will be considered for node routing.
-     * If not specified, all logs are in scope.
-     *
-     * @example
-     * ```typescript
-     * scope: {
-     *   'deployment.environment': 'production',
-     *   'service.namespace': 'checkout'
-     * }
-     * ```
-     */
-    scope?: CanvasScope;
-    /**
-     * Audit configuration for log coverage tracking
-     *
-     * When enabled, tracks which logs are routed vs orphaned,
-     * detects silent nodes, and generates coverage reports.
-     */
-    audit?: CanvasAuditConfig;
-    /** Nodes - JSON Canvas types and/or OTEL node types */
-    nodes?: ExtendedCanvasNode[];
-    /** Edges with optional PV extensions */
-    edges?: ExtendedCanvasEdge[];
-    /**
-     * @deprecated The `pv` field is fully deprecated. All fields have been moved to top-level.
-     * Validation will error if this field is present.
-     *
-     * Migration:
-     * - `pv.name` → `name` (top-level)
-     * - `pv.markdown` → `markdown` (top-level)
-     * - `pv.description` → `description` (top-level)
-     * - `pv.nodeTypes` → `nodeTypes` (top-level)
-     * - `pv.edgeTypes` → `edgeTypes` (top-level)
-     * - `pv.display` → `display` (top-level)
-     * - `pv.pathConfig` → `pathConfig` (top-level)
-     * - `pv.scope` → `scope` (top-level)
-     * - `pv.audit` → `audit` (top-level)
-     * - `pv.version` → removed (not used)
-     */
-    pv?: PVCanvasExtension;
-}
-/**
- * Type guard for text nodes
- */
-export declare function isTextNode(node: CanvasNode | ExtendedCanvasNode): node is CanvasTextNode | ExtendedCanvasTextNode;
-/**
- * Type guard for file nodes
- */
-export declare function isFileNode(node: CanvasNode | ExtendedCanvasNode): node is CanvasFileNode | ExtendedCanvasFileNode;
-/**
- * Type guard for link nodes
- */
-export declare function isLinkNode(node: CanvasNode | ExtendedCanvasNode): node is CanvasLinkNode | ExtendedCanvasLinkNode;
-/**
- * Type guard for group nodes
- */
-export declare function isGroupNode(node: CanvasNode | ExtendedCanvasNode): node is CanvasGroupNode | ExtendedCanvasGroupNode;
-/**
- * Type guard for extended nodes (with PV extension)
- */
-export declare function hasPVExtension(node: CanvasNode | ExtendedCanvasNode): node is ExtendedCanvasNode;
-/**
- * Type guard for OTEL event nodes
- */
-export declare function isOtelEventNode(node: ExtendedCanvasNode): node is OtelEventNode;
-/**
- * Type guard for OTEL span convention nodes
- */
-export declare function isOtelSpanConventionNode(node: ExtendedCanvasNode): node is OtelSpanConventionNode;
-/**
- * Type guard for OTEL scope nodes
- */
-export declare function isOtelScopeNode(node: ExtendedCanvasNode): node is OtelScopeNode;
-/**
- * Type guard for OTEL resource nodes
- */
-export declare function isOtelResourceNode(node: ExtendedCanvasNode): node is OtelResourceNode;
-/**
- * Type guard for OTEL boundary nodes
- */
-export declare function isOtelBoundaryNode(node: ExtendedCanvasNode): node is OtelBoundaryNode;
-/**
- * Type guard for any OTEL node type
- */
-export declare function isOtelNode(node: ExtendedCanvasNode): node is OtelNode;
-/**
- * Type guard for standard canvas nodes (that may have pv extensions)
- */
-export declare function isStandardCanvasNode(node: ExtendedCanvasNode): node is ExtendedCanvasTextNode | ExtendedCanvasFileNode | ExtendedCanvasLinkNode | ExtendedCanvasGroupNode;
-/**
- * Get the identifier for an OTEL node (shown below the label)
- */
-export declare function getOtelNodeIdentifier(node: OtelNode): string | undefined;
-/**
- * Color preset mapping
- */
-export declare const CANVAS_COLOR_PRESETS: Record<number, string>;
-/**
- * Resolve a canvas color to a hex string
- *
- * Supports:
- * - Hex strings: "#22c55e" or "#3f6"
- * - Numeric presets: 1-6
- * - Numeric string presets: "1"-"6" (Obsidian Canvas format)
- */
-export declare function resolveCanvasColor(color: CanvasColor | undefined): string | undefined;
-//# sourceMappingURL=canvas.d.ts.map