@principal-ai/subsystems-core 0.29.0

package/dist/events/OtelEventPathsValidator.d.ts

@@ -0,0 +1,75 @@
+/**
+ * OTEL Event Paths Validator (Phase 2)
+ *
+ * Cross-canvas static check. For every `otel-event` node in an OTEL canvas,
+ * cross-reference each entry in `otel.files` against the `paths` declared on
+ * the event's namespace in the corresponding events canvas.
+ *
+ * Enforcement is opt-in per namespace: a namespace without `paths` (or a
+ * namespace not declared at all) produces no violations for its events.
+ *
+ * Pure/browser-safe — no filesystem access.
+ */
+import type { ExtendedCanvas } from '../types/canvas';
+/**
+ * One events canvas, pre-paired with the scope it owns. Scope pairing is
+ * typically derived via the existing scope → filename convention
+ * (e.g., scope `principal-view.cli` owns `principal-view-cli.events.canvas`).
+ */
+export interface EventsCanvasInput {
+    canvas: ExtendedCanvas;
+    canvasPath: string;
+    scope: string;
+}
+/**
+ * One OTEL canvas whose `otel-event` nodes we want to cross-check.
+ */
+export interface OtelCanvasInput {
+    canvas: ExtendedCanvas;
+    canvasPath: string;
+}
+export interface OtelEventPathsValidationContext {
+    eventsCanvases: EventsCanvasInput[];
+    otelCanvases: OtelCanvasInput[];
+}
+export type OtelEventPathsRuleId = 'events-otel-files-wrong-namespace' | 'events-otel-files-orphan';
+export interface OtelEventPathsViolation {
+    ruleId: OtelEventPathsRuleId;
+    severity: 'error' | 'warn';
+    file: string;
+    path?: string;
+    message: string;
+    impact: string;
+    suggestion: string;
+}
+export interface OtelEventPathsValidationResult {
+    valid: boolean;
+    violations: OtelEventPathsViolation[];
+    metrics: {
+        /** Events whose files were cross-checked against namespace paths. */
+        eventsChecked: number;
+        /** Total files examined across all checked events. */
+        filesChecked: number;
+        /**
+         * Events skipped because the event's namespace has no `paths` declared
+         * (or is not declared at all) — enforcement is opt-in per namespace.
+         */
+        eventsSkippedNoPaths: number;
+        /**
+         * Events skipped because the `otel-event` node declares no `otel.files`.
+         * These events have no claimed implementation location to cross-check.
+         */
+        eventsSkippedNoFiles: number;
+    };
+}
+export declare class OtelEventPathsValidator {
+    /**
+     * Build a path index from the events canvases, keyed by scope.
+     * Only namespaces that declare `paths` contribute entries.
+     */
+    private buildIndex;
+    /** Extract the namespace from an event name (all segments except the last). */
+    private extractNamespace;
+    validate(context: OtelEventPathsValidationContext): OtelEventPathsValidationResult;
+}
+//# sourceMappingURL=OtelEventPathsValidator.d.ts.map

package/dist/events/OtelEventPathsValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OtelEventPathsValidator.d.ts","sourceRoot":"","sources":["../../src/events/OtelEventPathsValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,iBAAiB,CAAC;AAIrE;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,cAAc,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,cAAc,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,+BAA+B;IAC9C,cAAc,EAAE,iBAAiB,EAAE,CAAC;IACpC,YAAY,EAAE,eAAe,EAAE,CAAC;CACjC;AAED,MAAM,MAAM,oBAAoB,GAC5B,mCAAmC,GACnC,0BAA0B,CAAC;AAE/B,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,8BAA8B;IAC7C,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,uBAAuB,EAAE,CAAC;IACtC,OAAO,EAAE;QACP,qEAAqE;QACrE,aAAa,EAAE,MAAM,CAAC;QACtB,sDAAsD;QACtD,YAAY,EAAE,MAAM,CAAC;QACrB;;;WAGG;QACH,oBAAoB,EAAE,MAAM,CAAC;QAC7B;;;WAGG;QACH,oBAAoB,EAAE,MAAM,CAAC;KAC9B,CAAC;CACH;AAED,qBAAa,uBAAuB;IAClC;;;OAGG;IACH,OAAO,CAAC,UAAU;IAqBlB,+EAA+E;IAC/E,OAAO,CAAC,gBAAgB;IAMxB,QAAQ,CAAC,OAAO,EAAE,+BAA+B,GAAG,8BAA8B;CAiFnF"}

package/dist/events/OtelEventPathsValidator.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * OTEL Event Paths Validator (Phase 2)
+ *
+ * Cross-canvas static check. For every `otel-event` node in an OTEL canvas,
+ * cross-reference each entry in `otel.files` against the `paths` declared on
+ * the event's namespace in the corresponding events canvas.
+ *
+ * Enforcement is opt-in per namespace: a namespace without `paths` (or a
+ * namespace not declared at all) produces no violations for its events.
+ *
+ * Pure/browser-safe — no filesystem access.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OtelEventPathsValidator = void 0;
+const canvas_1 = require("../types/canvas");
+const NamespacePathIndex_1 = require("./NamespacePathIndex");
+class OtelEventPathsValidator {
+    /**
+     * Build a path index from the events canvases, keyed by scope.
+     * Only namespaces that declare `paths` contribute entries.
+     */
+    buildIndex(eventsCanvases) {
+        const index = new NamespacePathIndex_1.NamespacePathIndex();
+        for (const ec of eventsCanvases) {
+            for (const node of ec.canvas.nodes || []) {
+                if (node?.type !== 'event-namespace')
+                    continue;
+                const ns = node.namespace;
+                if (!ns || typeof ns.name !== 'string')
+                    continue;
+                if (!Array.isArray(ns.paths) || ns.paths.length === 0)
+                    continue;
+                const entry = {
+                    scope: ec.scope,
+                    namespace: ns.name,
+                    paths: ns.paths,
+                    sourceCanvasPath: ec.canvasPath,
+                };
+                index.add(entry);
+            }
+        }
+        return index;
+    }
+    /** Extract the namespace from an event name (all segments except the last). */
+    extractNamespace(eventName) {
+        const segments = eventName.split('.');
+        if (segments.length < 2)
+            return null;
+        return segments.slice(0, -1).join('.');
+    }
+    validate(context) {
+        const violations = [];
+        const metrics = {
+            eventsChecked: 0,
+            filesChecked: 0,
+            eventsSkippedNoPaths: 0,
+            eventsSkippedNoFiles: 0,
+        };
+        const index = this.buildIndex(context.eventsCanvases);
+        for (const oc of context.otelCanvases) {
+            for (const node of oc.canvas.nodes || []) {
+                if (!(0, canvas_1.isOtelEventNode)(node))
+                    continue;
+                const eventNode = node;
+                const eventName = eventNode.event?.name;
+                const scope = eventNode.otel?.scope;
+                const files = eventNode.otel?.files;
+                if (!eventName || !scope)
+                    continue; // malformed — other validators catch this
+                const namespace = this.extractNamespace(eventName);
+                if (!namespace)
+                    continue; // invalid event name — caught by other validators
+                if (!files || files.length === 0) {
+                    metrics.eventsSkippedNoFiles++;
+                    continue;
+                }
+                // Enforcement is opt-in: if the event's namespace has no declared
+                // paths (or isn't declared at all), we don't check its files.
+                const eventEntry = index.getEntry(scope, namespace);
+                if (!eventEntry) {
+                    metrics.eventsSkippedNoPaths++;
+                    continue;
+                }
+                metrics.eventsChecked++;
+                for (const file of files) {
+                    metrics.filesChecked++;
+                    const match = index.resolve(scope, file);
+                    if (match === null) {
+                        violations.push({
+                            ruleId: 'events-otel-files-orphan',
+                            severity: 'warn',
+                            file: oc.canvasPath,
+                            path: `nodes[id="${eventNode.id}"].otel.files["${file}"]`,
+                            message: `Event "${eventName}" declares file "${file}" which is not covered by any namespace's paths in scope "${scope}"`,
+                            impact: 'The file emits an event but has no declared component home, so its location cannot be validated against namespace conventions.',
+                            suggestion: `Either add "${file}" (or an ancestor folder) to the "paths" of the "${namespace}" namespace in the events canvas, or move the implementation into one of the namespace's declared paths: ${eventEntry.paths.map((p) => `"${p}"`).join(', ')}.`,
+                        });
+                        continue;
+                    }
+                    if (match.entry.namespace === namespace) {
+                        // File belongs to the event's namespace (longest-prefix match).
+                        continue;
+                    }
+                    violations.push({
+                        ruleId: 'events-otel-files-wrong-namespace',
+                        severity: 'error',
+                        file: oc.canvasPath,
+                        path: `nodes[id="${eventNode.id}"].otel.files["${file}"]`,
+                        message: `Event "${eventName}" declares file "${file}", but namespace "${match.entry.namespace}" (path "${match.matchedPath}") owns that location — not "${namespace}"`,
+                        impact: 'Event identity disagrees with code location. Consumers discovering the event by name will land in a folder that belongs to a different namespace.',
+                        suggestion: `Either rename the event to start with "${match.entry.namespace}." (if the code placement is correct), or move the implementation into one of the "${namespace}" namespace's declared paths (${eventEntry.paths.map((p) => `"${p}"`).join(', ')}).`,
+                    });
+                }
+            }
+        }
+        const errors = violations.filter((v) => v.severity === 'error');
+        return {
+            valid: errors.length === 0,
+            violations,
+            metrics,
+        };
+    }
+}
+exports.OtelEventPathsValidator = OtelEventPathsValidator;
+//# sourceMappingURL=OtelEventPathsValidator.js.map

package/dist/events/OtelEventPathsValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OtelEventPathsValidator.js","sourceRoot":"","sources":["../../src/events/OtelEventPathsValidator.ts"],"names":[],"mappings":"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"}

package/dist/events/ScopeEventsValidator.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Scope Events Validator
+ *
+ * Validates that each instrumentation scope documented in architecture.scopes.canvas
+ * has a corresponding {scope-name}.events.canvas file documenting its event vocabulary.
+ */
+import type { FileSystemAdapter } from '@principal-ai/repository-abstraction';
+import type { ExtendedCanvas } from '../types/canvas';
+/**
+ * Scope events validation context
+ */
+export interface ScopeEventsValidationContext {
+    /** The scopes canvas (if found) */
+    scopesCanvas?: ExtendedCanvas;
+    /** Path to the scopes canvas file */
+    scopesCanvasPath?: string;
+    /** Base path for resolving relative paths */
+    basePath: string;
+}
+/**
+ * Scope events validation violation
+ */
+export interface ScopeEventsViolation {
+    /** Rule ID that detected this violation */
+    ruleId: string;
+    /** Severity level */
+    severity: 'error' | 'warn';
+    /** Scope name */
+    scope: string;
+    /** Expected file path */
+    expectedPath: string;
+    /** Human-readable description of what's wrong */
+    message: string;
+    /** Why this matters */
+    impact: string;
+    /** How to fix it */
+    suggestion: string;
+}
+/**
+ * Scope events validation result
+ */
+export interface ScopeEventsValidationResult {
+    /** Whether validation passed (no errors) */
+    valid: boolean;
+    /** List of violations found */
+    violations: ScopeEventsViolation[];
+    /** Summary of events canvas coverage */
+    coverage: {
+        /** Total owned scopes from library.yaml */
+        totalScopes: number;
+        /** Scopes with events canvas files */
+        scopesWithEvents: string[];
+        /** Scopes missing events canvas */
+        scopesMissingEvents: string[];
+    };
+}
+/**
+ * Validates that scopes have corresponding events canvas files
+ */
+export declare class ScopeEventsValidator {
+    private fsAdapter;
+    constructor(fsAdapter: FileSystemAdapter);
+    /**
+     * Validate that each scope documented in scopes canvas has an events canvas
+     */
+    validate(context: ScopeEventsValidationContext): Promise<ScopeEventsValidationResult>;
+}
+//# sourceMappingURL=ScopeEventsValidator.d.ts.map

package/dist/events/ScopeEventsValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScopeEventsValidator.d.ts","sourceRoot":"","sources":["../../src/events/ScopeEventsValidator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,iBAAiB,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,mCAAmC;IACnC,YAAY,CAAC,EAAE,cAAc,CAAC;IAE9B,qCAAqC;IACrC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IAEf,qBAAqB;IACrB,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IAE3B,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IAEd,yBAAyB;IACzB,YAAY,EAAE,MAAM,CAAC;IAErB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAEhB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IAEf,oBAAoB;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,4CAA4C;IAC5C,KAAK,EAAE,OAAO,CAAC;IAEf,+BAA+B;IAC/B,UAAU,EAAE,oBAAoB,EAAE,CAAC;IAEnC,wCAAwC;IACxC,QAAQ,EAAE;QACR,2CAA2C;QAC3C,WAAW,EAAE,MAAM,CAAC;QACpB,sCAAsC;QACtC,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAC3B,mCAAmC;QACnC,mBAAmB,EAAE,MAAM,EAAE,CAAC;KAC/B,CAAC;CACH;AAUD;;GAEG;AACH,qBAAa,oBAAoB;IACnB,OAAO,CAAC,SAAS;gBAAT,SAAS,EAAE,iBAAiB;IAEhD;;OAEG;IACG,QAAQ,CAAC,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAAC,2BAA2B,CAAC;CAqE5F"}

package/dist/events/ScopeEventsValidator.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Scope Events Validator
+ *
+ * Validates that each instrumentation scope documented in architecture.scopes.canvas
+ * has a corresponding {scope-name}.events.canvas file documenting its event vocabulary.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopeEventsValidator = void 0;
+/**
+ * Convert scope name to events canvas filename
+ * e.g., "backlog.md.cli" -> "backlog-md-cli.events.canvas"
+ */
+function scopeToEventsCanvasFilename(scope) {
+    return `${scope.replace(/\./g, '-')}.events.canvas`;
+}
+/**
+ * Validates that scopes have corresponding events canvas files
+ */
+class ScopeEventsValidator {
+    constructor(fsAdapter) {
+        this.fsAdapter = fsAdapter;
+    }
+    /**
+     * Validate that each scope documented in scopes canvas has an events canvas
+     */
+    async validate(context) {
+        const violations = [];
+        const { scopesCanvas, scopesCanvasPath, basePath } = context;
+        const scopesWithEvents = [];
+        const scopesMissingEvents = [];
+        // If no scopes canvas, nothing to validate
+        if (!scopesCanvas) {
+            return {
+                valid: true,
+                violations: [],
+                coverage: {
+                    totalScopes: 0,
+                    scopesWithEvents: [],
+                    scopesMissingEvents: [],
+                },
+            };
+        }
+        // Extract scope nodes from the canvas
+        const scopeNodes = (scopesCanvas.nodes || []).filter((node) => node.type === 'otel-scope');
+        // Check each scope for corresponding events canvas
+        for (const scopeNode of scopeNodes) {
+            const scope = scopeNode.otel?.scope;
+            if (!scope)
+                continue;
+            const eventsCanvasFilename = scopeToEventsCanvasFilename(scope);
+            const eventsCanvasPath = this.fsAdapter.join(basePath, '.principal-views', eventsCanvasFilename);
+            const relativePath = `.principal-views/${eventsCanvasFilename}`;
+            if (await this.fsAdapter.exists(eventsCanvasPath)) {
+                scopesWithEvents.push(scope);
+            }
+            else {
+                scopesMissingEvents.push(scope);
+                violations.push({
+                    ruleId: 'scope-events-canvas-required',
+                    severity: 'warn',
+                    scope,
+                    expectedPath: relativePath,
+                    message: `Scope "${scope}" is missing an events canvas`,
+                    impact: `Event vocabulary for scope "${scope}" is not documented. This makes it impossible to:
+- Understand what events the scope emits
+- Validate event flows match actual code
+- Track event schema changes over time
+- Generate documentation for implementers`,
+                    suggestion: `Create ${relativePath} that documents:
+- Event namespaces (groups of related events like "validation", "file", etc.)
+- Events within each namespace with their attributes
+- Adjacency relationships (which event namespaces connect in workflows)
+
+See architecture.events.md for conventions.`,
+                });
+            }
+        }
+        return {
+            valid: violations.filter(v => v.severity === 'error').length === 0,
+            violations,
+            coverage: {
+                totalScopes: scopeNodes.length,
+                scopesWithEvents,
+                scopesMissingEvents,
+            },
+        };
+    }
+}
+exports.ScopeEventsValidator = ScopeEventsValidator;
+//# sourceMappingURL=ScopeEventsValidator.js.map

package/dist/events/ScopeEventsValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScopeEventsValidator.js","sourceRoot":"","sources":["../../src/events/ScopeEventsValidator.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAkEH;;;GAGG;AACH,SAAS,2BAA2B,CAAC,KAAa;IAChD,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,gBAAgB,CAAC;AACtD,CAAC;AAED;;GAEG;AACH,MAAa,oBAAoB;IAC/B,YAAoB,SAA4B;QAA5B,cAAS,GAAT,SAAS,CAAmB;IAAG,CAAC;IAEpD;;OAEG;IACH,KAAK,CAAC,QAAQ,CAAC,OAAqC;QAClD,MAAM,UAAU,GAA2B,EAAE,CAAC;QAC9C,MAAM,EAAE,YAAY,EAAE,gBAAgB,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;QAE7D,MAAM,gBAAgB,GAAa,EAAE,CAAC;QACtC,MAAM,mBAAmB,GAAa,EAAE,CAAC;QAEzC,2CAA2C;QAC3C,IAAI,CAAC,YAAY,EAAE;YACjB,OAAO;gBACL,KAAK,EAAE,IAAI;gBACX,UAAU,EAAE,EAAE;gBACd,QAAQ,EAAE;oBACR,WAAW,EAAE,CAAC;oBACd,gBAAgB,EAAE,EAAE;oBACpB,mBAAmB,EAAE,EAAE;iBACxB;aACF,CAAC;SACH;QAED,sCAAsC;QACtC,MAAM,UAAU,GAAG,CAAC,YAAY,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,CAClD,CAAC,IAAI,EAAyB,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,YAAY,CAC5D,CAAC;QAEF,mDAAmD;QACnD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE;YAClC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC;YACpC,IAAI,CAAC,KAAK;gBAAE,SAAS;YAErB,MAAM,oBAAoB,GAAG,2BAA2B,CAAC,KAAK,CAAC,CAAC;YAChE,MAAM,gBAAgB,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,kBAAkB,EAAE,oBAAoB,CAAC,CAAC;YACjG,MAAM,YAAY,GAAG,oBAAoB,oBAAoB,EAAE,CAAC;YAEhE,IAAI,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE;gBACjD,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;aAC9B;iBAAM;gBACL,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBAChC,UAAU,CAAC,IAAI,CAAC;oBACd,MAAM,EAAE,8BAA8B;oBACtC,QAAQ,EAAE,MAAM;oBAChB,KAAK;oBACL,YAAY,EAAE,YAAY;oBAC1B,OAAO,EAAE,UAAU,KAAK,+BAA+B;oBACvD,MAAM,EAAE,+BAA+B,KAAK;;;;0CAIZ;oBAChC,UAAU,EAAE,UAAU,YAAY;;;;;4CAKA;iBACnC,CAAC,CAAC;aACJ;SACF;QAED,OAAO;YACL,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC;YAClE,UAAU;YACV,QAAQ,EAAE;gBACR,WAAW,EAAE,UAAU,CAAC,MAAM;gBAC9B,gBAAgB;gBAChB,mBAAmB;aACpB;SACF,CAAC;IACJ,CAAC;CACF;AA3ED,oDA2EC"}

package/dist/events/index.d.ts

@@ -0,0 +1,9 @@
+export { EventsCanvasValidator } from './EventsCanvasValidator';
+export type { EventNamespaceNode, EventsCanvasValidationContext, EventsCanvasViolation, EventsCanvasValidationResult, } from './EventsCanvasValidator';
+export { ScopeEventsValidator } from './ScopeEventsValidator';
+export type { ScopeEventsValidationContext, ScopeEventsViolation, ScopeEventsValidationResult, } from './ScopeEventsValidator';
+export { NamespacePathIndex } from './NamespacePathIndex';
+export type { NamespacePathEntry, NamespacePathMatch } from './NamespacePathIndex';
+export { OtelEventPathsValidator } from './OtelEventPathsValidator';
+export type { OtelEventPathsValidationContext, OtelEventPathsValidationResult, OtelEventPathsViolation, OtelEventPathsRuleId, EventsCanvasInput, OtelCanvasInput, } from './OtelEventPathsValidator';
+//# sourceMappingURL=index.d.ts.map

package/dist/events/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,YAAY,EACV,kBAAkB,EAClB,6BAA6B,EAC7B,qBAAqB,EACrB,4BAA4B,GAC7B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EACV,4BAA4B,EAC5B,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAEnF,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,YAAY,EACV,+BAA+B,EAC/B,8BAA8B,EAC9B,uBAAuB,EACvB,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,GAChB,MAAM,2BAA2B,CAAC"}

package/dist/events/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OtelEventPathsValidator = exports.NamespacePathIndex = exports.ScopeEventsValidator = exports.EventsCanvasValidator = void 0;
+var EventsCanvasValidator_1 = require("./EventsCanvasValidator");
+Object.defineProperty(exports, "EventsCanvasValidator", { enumerable: true, get: function () { return EventsCanvasValidator_1.EventsCanvasValidator; } });
+var ScopeEventsValidator_1 = require("./ScopeEventsValidator");
+Object.defineProperty(exports, "ScopeEventsValidator", { enumerable: true, get: function () { return ScopeEventsValidator_1.ScopeEventsValidator; } });
+var NamespacePathIndex_1 = require("./NamespacePathIndex");
+Object.defineProperty(exports, "NamespacePathIndex", { enumerable: true, get: function () { return NamespacePathIndex_1.NamespacePathIndex; } });
+var OtelEventPathsValidator_1 = require("./OtelEventPathsValidator");
+Object.defineProperty(exports, "OtelEventPathsValidator", { enumerable: true, get: function () { return OtelEventPathsValidator_1.OtelEventPathsValidator; } });
+//# sourceMappingURL=index.js.map

package/dist/events/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":";;;AAAA,iEAAgE;AAAvD,8HAAA,qBAAqB,OAAA;AAQ9B,+DAA8D;AAArD,4HAAA,oBAAoB,OAAA;AAO7B,2DAA0D;AAAjD,wHAAA,kBAAkB,OAAA;AAG3B,qEAAoE;AAA3D,kIAAA,uBAAuB,OAAA"}

package/dist/events/path-helpers.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Path helpers shared across events-canvas validators.
+ *
+ * Paths declared in canvases (namespace `paths`, `otel.files`, etc.) are
+ * always repo-relative. These helpers give a consistent notion of
+ * canonicalization and prefix-based containment so that separate validators
+ * don't drift.
+ */
+/**
+ * Canonicalize a declared path for comparison.
+ * Strips leading `./`, trailing slashes, and collapses duplicate slashes.
+ */
+export declare function normalizePath(p: string): string;
+/**
+ * True when `child` is strictly nested under `parent` (not equal).
+ * Both inputs should already be normalized.
+ */
+export declare function isPathDescendant(child: string, parent: string): boolean;
+/**
+ * True when `filepath` is covered by `declaredPath` — either equal to it
+ * (file match) or nested under it (folder match). Inputs are normalized
+ * internally so callers can pass raw canvas values.
+ */
+export declare function pathCovers(declaredPath: string, filepath: string): boolean;
+/**
+ * Classify the relationship between two declared paths.
+ * - 'none':      disjoint — no overlap
+ * - 'partition': one is strictly a parent of the other — valid nested-namespace case
+ *                (longest-prefix wins at runtime, parent/child partition the tree)
+ * - 'conflict':  identical, or overlap that isn't a clean parent-child partition
+ */
+export declare function pathsOverlap(a: string, b: string): 'none' | 'partition' | 'conflict';
+//# sourceMappingURL=path-helpers.d.ts.map

package/dist/events/path-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-helpers.d.ts","sourceRoot":"","sources":["../../src/events/path-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAEvE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAI1E;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,CAMpF"}

package/dist/events/path-helpers.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Path helpers shared across events-canvas validators.
+ *
+ * Paths declared in canvases (namespace `paths`, `otel.files`, etc.) are
+ * always repo-relative. These helpers give a consistent notion of
+ * canonicalization and prefix-based containment so that separate validators
+ * don't drift.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pathsOverlap = exports.pathCovers = exports.isPathDescendant = exports.normalizePath = void 0;
+/**
+ * Canonicalize a declared path for comparison.
+ * Strips leading `./`, trailing slashes, and collapses duplicate slashes.
+ */
+function normalizePath(p) {
+    return p
+        .replace(/^\.\//, '')
+        .replace(/\/+$/, '')
+        .replace(/\/+/g, '/');
+}
+exports.normalizePath = normalizePath;
+/**
+ * True when `child` is strictly nested under `parent` (not equal).
+ * Both inputs should already be normalized.
+ */
+function isPathDescendant(child, parent) {
+    return child.startsWith(parent + '/');
+}
+exports.isPathDescendant = isPathDescendant;
+/**
+ * True when `filepath` is covered by `declaredPath` — either equal to it
+ * (file match) or nested under it (folder match). Inputs are normalized
+ * internally so callers can pass raw canvas values.
+ */
+function pathCovers(declaredPath, filepath) {
+    const d = normalizePath(declaredPath);
+    const f = normalizePath(filepath);
+    return d === f || isPathDescendant(f, d);
+}
+exports.pathCovers = pathCovers;
+/**
+ * Classify the relationship between two declared paths.
+ * - 'none':      disjoint — no overlap
+ * - 'partition': one is strictly a parent of the other — valid nested-namespace case
+ *                (longest-prefix wins at runtime, parent/child partition the tree)
+ * - 'conflict':  identical, or overlap that isn't a clean parent-child partition
+ */
+function pathsOverlap(a, b) {
+    const na = normalizePath(a);
+    const nb = normalizePath(b);
+    if (na === nb)
+        return 'conflict';
+    if (isPathDescendant(na, nb) || isPathDescendant(nb, na))
+        return 'partition';
+    return 'none';
+}
+exports.pathsOverlap = pathsOverlap;
+//# sourceMappingURL=path-helpers.js.map

package/dist/events/path-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-helpers.js","sourceRoot":"","sources":["../../src/events/path-helpers.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH;;;GAGG;AACH,SAAgB,aAAa,CAAC,CAAS;IACrC,OAAO,CAAC;SACL,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;SACpB,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;SACnB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAC1B,CAAC;AALD,sCAKC;AAED;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,KAAa,EAAE,MAAc;IAC5D,OAAO,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;AACxC,CAAC;AAFD,4CAEC;AAED;;;;GAIG;AACH,SAAgB,UAAU,CAAC,YAAoB,EAAE,QAAgB;IAC/D,MAAM,CAAC,GAAG,aAAa,CAAC,YAAY,CAAC,CAAC;IACtC,MAAM,CAAC,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IAClC,OAAO,CAAC,KAAK,CAAC,IAAI,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC3C,CAAC;AAJD,gCAIC;AAED;;;;;;GAMG;AACH,SAAgB,YAAY,CAAC,CAAS,EAAE,CAAS;IAC/C,MAAM,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;IAC5B,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,UAAU,CAAC;IACjC,IAAI,gBAAgB,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,gBAAgB,CAAC,EAAE,EAAE,EAAE,CAAC;QAAE,OAAO,WAAW,CAAC;IAC7E,OAAO,MAAM,CAAC;AAChB,CAAC;AAND,oCAMC"}

package/dist/execution/ExecutionLoader.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Execution loader for managing execution artifact files
+ *
+ * Supports loading execution files (.otel.json) from __executions__/ folders
+ * using the adapter pattern for environment-agnostic file operations.
+ *
+ * Automatically handles both OTLP standard format and legacy formats
+ * through ExecutionValidator conversion.
+ */
+import type { FileSystemAdapter } from '@principal-ai/repository-abstraction';
+import { type ExecutionData } from './ExecutionValidator';
+/**
+ * Represents a single execution file
+ */
+export interface ExecutionFile {
+    /** Execution name (filename without .otel.json extension) */
+    name: string;
+    /** Full path to the execution file */
+    path: string;
+    /** Parsed and validated execution data */
+    data: ExecutionData;
+}
+/**
+ * Result of loading all executions
+ */
+export interface ExecutionLoadResult {
+    /** Successfully loaded executions */
+    executions: ExecutionFile[];
+    /** Errors encountered during loading */
+    errors: Array<{
+        file: string;
+        error: string;
+    }>;
+}
+/**
+ * Loader for managing execution artifact files from __executions__/ folders
+ *
+ * @example
+ * ```typescript
+ * const loader = new ExecutionLoader(fsAdapter);
+ *
+ * // Check if __executions__/ exists
+ * if (await loader.hasExecutionDirectory('/path/to/project')) {
+ *   // Load all execution files
+ *   const result = await loader.loadAll('/path/to/project');
+ *   console.log(`Loaded ${result.executions.length} executions`);
+ *
+ *   // Load specific execution
+ *   const execution = await loader.loadByName('test-run', '/path/to/project');
+ * }
+ * ```
+ */
+export declare class ExecutionLoader {
+    private fsAdapter;
+    private static readonly EXECUTION_DIR;
+    private static readonly EXECUTION_EXTENSION;
+    private validator;
+    constructor(fsAdapter: FileSystemAdapter);
+    /**
+     * Check if __executions__/ directory exists
+     *
+     * @param baseDir - Base directory to search from
+     * @returns True if __executions__/ directory exists
+     */
+    hasExecutionDirectory(baseDir: string): Promise<boolean>;
+    /**
+     * List all available execution names in __executions__/ folder
+     *
+     * @param baseDir - Base directory containing __executions__/ folder
+     * @returns Array of execution names (without .otel.json extensions)
+     */
+    listExecutions(baseDir: string): Promise<string[]>;
+    /**
+     * Load a specific execution by name
+     *
+     * Automatically handles OTLP format conversion through ExecutionValidator.
+     *
+     * @param name - Execution name (without .otel.json extension)
+     * @param baseDir - Base directory containing __executions__/ folder
+     * @returns Execution file or null if not found/invalid
+     */
+    loadByName(name: string, baseDir: string): Promise<ExecutionFile | null>;
+    /**
+     * Load all executions from __executions__/ folder
+     *
+     * Automatically handles OTLP format conversion for all files.
+     *
+     * @param baseDir - Base directory containing __executions__/ folder
+     * @returns Result containing all loaded executions and any errors
+     */
+    loadAll(baseDir: string): Promise<ExecutionLoadResult>;
+    /**
+     * Get the execution directory path
+     *
+     * @param baseDir - Base directory
+     * @returns Full path to __executions__/ directory
+     */
+    getExecutionDirectoryPath(baseDir: string): string;
+    /**
+     * Search for __executions__/ directories recursively in a project
+     *
+     * Useful for monorepos where executions might be in multiple packages.
+     *
+     * @param baseDir - Base directory to search from
+     * @param maxDepth - Maximum directory depth to search (default: 3)
+     * @returns Array of paths to __executions__/ directories
+     */
+    findExecutionDirectories(baseDir: string, maxDepth?: number): Promise<string[]>;
+    /**
+     * Load all executions from multiple __executions__/ directories
+     *
+     * Useful for monorepos where executions are spread across packages.
+     *
+     * @param baseDir - Base directory to search from
+     * @param maxDepth - Maximum directory depth to search (default: 3)
+     * @returns Result containing all loaded executions and any errors
+     */
+    loadAllRecursive(baseDir: string, maxDepth?: number): Promise<ExecutionLoadResult>;
+    /**
+     * Check if a filename is an execution file
+     */
+    private isExecutionFile;
+    /**
+     * Extract execution name from filename
+     */
+    private getExecutionNameFromFilename;
+}
+/**
+ * Create a new execution loader instance
+ *
+ * @param fsAdapter - File system adapter for environment-agnostic operations
+ * @returns ExecutionLoader instance
+ */
+export declare function createExecutionLoader(fsAdapter: FileSystemAdapter): ExecutionLoader;
+//# sourceMappingURL=ExecutionLoader.d.ts.map