@principal-ai/subsystems-core 0.29.0

package/dist/types/canvas-scope.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Canvas Scope Types
+ *
+ * Defines which logs are relevant to a canvas. Only logs matching the canvas
+ * scope are considered for node routing. This acts as a pre-filter before
+ * individual node matching.
+ *
+ * @example
+ * ```yaml
+ * # Canvas configuration
+ * canvas:
+ *   id: "checkout-system"
+ *   scope:
+ *     deployment.environment: "production"
+ *     service.namespace: "checkout"
+ *   audit:
+ *     enabled: true
+ *     orphanThreshold: 100
+ *     coverageTarget: 95
+ * ```
+ */
+import type { ResourceMatch } from './resource-match';
+/**
+ * Canvas scope - filters which logs are processed by this canvas
+ *
+ * Extends ResourceMatch, so all matching operators are available.
+ * All conditions must match for a log to be "in scope" (AND logic).
+ *
+ * @example
+ * ```typescript
+ * // Only process production logs from the checkout namespace
+ * const scope: CanvasScope = {
+ *   'deployment.environment': 'production',
+ *   'service.namespace': { oneOf: ['checkout', 'payment'] }
+ * };
+ * ```
+ */
+export interface CanvasScope extends ResourceMatch {
+}
+/**
+ * Duration string format
+ *
+ * Supports common time units: ms, s, m, h, d
+ *
+ * @example "30s", "5m", "1h", "24h", "7d"
+ */
+export type DurationString = string;
+/**
+ * Audit configuration for a canvas
+ *
+ * Controls how log routing is monitored and reported.
+ */
+export interface CanvasAuditConfig {
+    /**
+     * Enable audit collection
+     * When enabled, the system tracks:
+     * - Log counts per node
+     * - Orphaned logs (in scope but unmatched)
+     * - Silent nodes (defined but receiving no logs)
+     */
+    enabled: boolean;
+    /**
+     * Alert threshold for orphaned logs
+     *
+     * If the number of orphaned logs exceeds this count within
+     * the audit period, an alert or warning is generated.
+     *
+     * @default undefined (no threshold)
+     */
+    orphanThreshold?: number;
+    /**
+     * Duration after which a silent node triggers an alert
+     *
+     * If a node receives no logs for this duration, it's flagged
+     * as potentially misconfigured or the service may be down.
+     *
+     * @example "1h", "30m", "24h"
+     * @default undefined (no alerting)
+     */
+    silentNodeAlertAfter?: DurationString;
+    /**
+     * Target coverage percentage (0-100)
+     *
+     * The expected percentage of in-scope logs that should be
+     * routed to nodes. Used for coverage analysis and alerts.
+     *
+     * @example 95 (expect 95% of logs to match a node)
+     * @default undefined (no target)
+     */
+    coverageTarget?: number;
+    /**
+     * Maximum number of orphan signatures to track
+     *
+     * Orphans are grouped by their resource signature. This limits
+     * memory usage by capping the number of unique signatures tracked.
+     *
+     * @default 1000
+     */
+    maxOrphanSignatures?: number;
+    /**
+     * Maximum sample logs per orphan signature
+     *
+     * Number of sample log bodies to keep per orphan group for debugging.
+     *
+     * @default 5
+     */
+    maxSamplesPerOrphan?: number;
+}
+/**
+ * Canvas-level configuration for log association
+ *
+ * Top-level configuration that defines scope and audit settings
+ * for a canvas.
+ */
+export interface CanvasLogAssociation {
+    /**
+     * Unique canvas identifier
+     *
+     * Used for routing logs to the correct canvas when multiple
+     * canvases are active, and for audit reports.
+     */
+    id: string;
+    /**
+     * Scope filter
+     *
+     * Only logs matching this scope are considered for node routing.
+     * If not specified, all logs are in scope.
+     */
+    scope?: CanvasScope;
+    /**
+     * Audit configuration
+     *
+     * If not specified, auditing is disabled.
+     */
+    audit?: CanvasAuditConfig;
+}
+/**
+ * Default audit configuration values
+ */
+export declare const DEFAULT_AUDIT_CONFIG: Partial<CanvasAuditConfig>;
+/**
+ * Parse a duration string to milliseconds
+ *
+ * @param duration Duration string like "30s", "5m", "1h"
+ * @returns Duration in milliseconds, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * parseDuration('30s');  // 30000
+ * parseDuration('5m');   // 300000
+ * parseDuration('1h');   // 3600000
+ * parseDuration('24h');  // 86400000
+ * ```
+ */
+export declare function parseDuration(duration: DurationString): number | null;
+//# sourceMappingURL=canvas-scope.d.ts.map

package/dist/types/canvas-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-scope.d.ts","sourceRoot":"","sources":["../../src/types/canvas-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,WAAY,SAAQ,aAAa;CAGjD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC;AAEpC;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,cAAc,CAAC;IAEtC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;;;;OAKG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;IAEpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,OAAO,CAAC,iBAAiB,CAG3D,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CAgBrE"}

package/dist/types/canvas-scope.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Canvas Scope Types
+ *
+ * Defines which logs are relevant to a canvas. Only logs matching the canvas
+ * scope are considered for node routing. This acts as a pre-filter before
+ * individual node matching.
+ *
+ * @example
+ * ```yaml
+ * # Canvas configuration
+ * canvas:
+ *   id: "checkout-system"
+ *   scope:
+ *     deployment.environment: "production"
+ *     service.namespace: "checkout"
+ *   audit:
+ *     enabled: true
+ *     orphanThreshold: 100
+ *     coverageTarget: 95
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDuration = exports.DEFAULT_AUDIT_CONFIG = void 0;
+/**
+ * Default audit configuration values
+ */
+exports.DEFAULT_AUDIT_CONFIG = {
+    maxOrphanSignatures: 1000,
+    maxSamplesPerOrphan: 5,
+};
+/**
+ * Parse a duration string to milliseconds
+ *
+ * @param duration Duration string like "30s", "5m", "1h"
+ * @returns Duration in milliseconds, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * parseDuration('30s');  // 30000
+ * parseDuration('5m');   // 300000
+ * parseDuration('1h');   // 3600000
+ * parseDuration('24h');  // 86400000
+ * ```
+ */
+function parseDuration(duration) {
+    const match = duration.match(/^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/);
+    if (!match)
+        return null;
+    const value = parseFloat(match[1]);
+    const unit = match[2];
+    const multipliers = {
+        ms: 1,
+        s: 1000,
+        m: 60 * 1000,
+        h: 60 * 60 * 1000,
+        d: 24 * 60 * 60 * 1000,
+    };
+    return value * multipliers[unit];
+}
+exports.parseDuration = parseDuration;
+//# sourceMappingURL=canvas-scope.js.map

package/dist/types/canvas-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-scope.js","sourceRoot":"","sources":["../../src/types/canvas-scope.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAmIH;;GAEG;AACU,QAAA,oBAAoB,GAA+B;IAC9D,mBAAmB,EAAE,IAAI;IACzB,mBAAmB,EAAE,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,SAAgB,aAAa,CAAC,QAAwB;IACpD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;IAC9D,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAExB,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAEtB,MAAM,WAAW,GAA2B;QAC1C,EAAE,EAAE,CAAC;QACL,CAAC,EAAE,IAAI;QACP,CAAC,EAAE,EAAE,GAAG,IAAI;QACZ,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI;QACjB,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;KACvB,CAAC;IAEF,OAAO,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC;AAhBD,sCAgBC"}