@principal-ai/subsystems-core 0.29.0 → 0.31.0

package/dist/events/OtelEventPathsValidator.d.ts

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

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

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

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

package/dist/events/ScopeEventsValidator.d.ts

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

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

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

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

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

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

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

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

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

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

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

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

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