@principal-ai/subsystems-core 0.29.0 → 0.30.0

package/dist/telemetry/event-validator.js

@@ -1,257 +0,0 @@
-"use strict";
-/**
- * Event Validator
- *
- * Type-safe telemetry event validation against canvas event schemas.
- * Ensures that emitted events match the schema defined in the canvas.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createValidatedEmitter = exports.EventValidator = exports.EventValidationError = void 0;
-const canvas_1 = require("../types/canvas");
-/**
- * Validation error for telemetry events
- */
-class EventValidationError extends Error {
-    constructor(eventName, nodeId, errors) {
-        super(`Event validation failed for '${eventName}' on node '${nodeId}':\n${errors.join('\n')}`);
-        this.eventName = eventName;
-        this.nodeId = nodeId;
-        this.errors = errors;
-        this.name = 'EventValidationError';
-    }
-}
-exports.EventValidationError = EventValidationError;
-/**
- * Event validator that checks events against canvas schema
- */
-class EventValidator {
-    constructor(canvas, library) {
-        this.eventSchemasByNode = new Map();
-        this.eventSchemasByName = new Map();
-        this.nodeIdsByBaseId = new Map();
-        this.library = library;
-        this.indexEventSchemas(canvas);
-    }
-    /**
-     * Index all event schemas from canvas nodes
-     */
-    indexEventSchemas(canvas) {
-        if (!canvas.nodes)
-            return;
-        for (const node of canvas.nodes) {
-            let eventSchema;
-            // Check OTEL event node (top-level event/eventRef)
-            if ((0, canvas_1.isOtelEventNode)(node)) {
-                if (node.event) {
-                    eventSchema = node.event;
-                }
-                else if (node.eventRef) {
-                    eventSchema = this.resolveLibraryEvent(node.eventRef);
-                    if (!eventSchema) {
-                        console.warn(`Node '${node.id}' references unknown library event '${node.eventRef}'`);
-                        continue;
-                    }
-                }
-            }
-            // Check standard node (pv.event/pv.eventRef)
-            else if ((0, canvas_1.isStandardCanvasNode)(node)) {
-                if (node.pv?.event) {
-                    eventSchema = node.pv.event;
-                }
-                else if (node.pv?.eventRef) {
-                    eventSchema = this.resolveLibraryEvent(node.pv.eventRef);
-                    if (!eventSchema) {
-                        console.warn(`Node '${node.id}' references unknown library event '${node.pv.eventRef}'`);
-                        continue;
-                    }
-                }
-            }
-            if (eventSchema) {
-                // Index by node ID
-                this.eventSchemasByNode.set(node.id, eventSchema);
-                // Index by event name
-                this.eventSchemasByName.set(eventSchema.name, eventSchema);
-                // Index by base node ID (strip numeric suffixes like '-2', '-3')
-                const baseId = node.id.replace(/-\d+$/, '');
-                if (!this.nodeIdsByBaseId.has(baseId)) {
-                    this.nodeIdsByBaseId.set(baseId, new Set());
-                }
-                this.nodeIdsByBaseId.get(baseId).add(node.id);
-            }
-        }
-    }
-    /**
-     * Resolve an event schema from library by event name
-     */
-    resolveLibraryEvent(eventName) {
-        if (!this.library?.eventSchemas) {
-            return undefined;
-        }
-        const librarySchema = this.library.eventSchemas[eventName];
-        if (!librarySchema) {
-            return undefined;
-        }
-        // Convert library schema (without name) to full PVEventSchema
-        return {
-            name: eventName,
-            description: librarySchema.description,
-            attributes: librarySchema.attributes,
-        };
-    }
-    /**
-     * Validate an event against the schema for a specific node
-     */
-    validate(nodeId, eventName, attributes) {
-        const errors = [];
-        // First try to find schema by event name (supports multiple events per component)
-        const eventSchema = this.eventSchemasByName.get(eventName);
-        // If not found by event name, check if the specific node has a schema
-        if (!eventSchema) {
-            // Check exact node ID first
-            const nodeSchema = this.eventSchemasByNode.get(nodeId);
-            if (nodeSchema) {
-                // Node has a schema, but this event doesn't exist anywhere
-                errors.push(`Event '${eventName}' is not defined in schema for node '${nodeId}'`);
-                return { valid: false, errors };
-            }
-            // Check base ID pattern (e.g., "graph-converter" for "graph-converter-1", etc.)
-            const baseId = nodeId.replace(/-\d+$/, '');
-            if (this.nodeIdsByBaseId.has(baseId)) {
-                // Component has schemas defined, but this event doesn't exist
-                errors.push(`Event '${eventName}' is not defined in schema for node '${nodeId}'`);
-                return { valid: false, errors };
-            }
-            // No schema defined at all - allow all events (permissive mode)
-            return { valid: true, errors: [] };
-        }
-        // Verify event name matches (this should always be true now, but keeping for safety)
-        if (eventSchema.name !== eventName) {
-            errors.push(`Event '${eventName}' does not match schema event name '${eventSchema.name}' for node '${nodeId}'`);
-            return { valid: false, errors };
-        }
-        // Validate each field in the schema
-        for (const [fieldName, fieldSchema] of Object.entries(eventSchema.attributes)) {
-            const value = attributes[fieldName];
-            // Check required fields
-            if (fieldSchema.required && value === undefined) {
-                errors.push(`Required field '${fieldName}' is missing`);
-                continue;
-            }
-            // Skip validation if field is not present and not required
-            if (value === undefined) {
-                continue;
-            }
-            // Validate type
-            const actualType = this.getValueType(value);
-            if (actualType !== fieldSchema.type) {
-                errors.push(`Field '${fieldName}' has type '${actualType}' but schema expects '${fieldSchema.type}'`);
-            }
-        }
-        // Check for unexpected fields (strict mode)
-        const schemaFields = new Set(Object.keys(eventSchema.attributes));
-        for (const fieldName of Object.keys(attributes)) {
-            // Allow special metadata fields
-            if (fieldName.startsWith('code.') || fieldName === 'description') {
-                continue;
-            }
-            if (!schemaFields.has(fieldName)) {
-                // Just a warning, not an error
-                // errors.push(`Unexpected field '${fieldName}' not in schema`);
-            }
-        }
-        return {
-            valid: errors.length === 0,
-            errors,
-        };
-    }
-    /**
-     * Get the type of a value
-     */
-    getValueType(value) {
-        if (Array.isArray(value))
-            return 'array';
-        if (value === null)
-            return 'object';
-        return typeof value;
-    }
-    /**
-     * Get event schema for a node
-     */
-    getNodeSchema(nodeId) {
-        return this.eventSchemasByNode.get(nodeId);
-    }
-    /**
-     * Get event name for a node
-     */
-    getNodeEventName(nodeId) {
-        const schema = this.eventSchemasByNode.get(nodeId);
-        return schema?.name;
-    }
-    /**
-     * Get all event names for a node (including related nodes with same base ID)
-     */
-    getNodeEventNames(nodeId) {
-        const baseId = nodeId.replace(/-\d+$/, '');
-        const relatedNodeIds = this.nodeIdsByBaseId.get(baseId);
-        if (!relatedNodeIds) {
-            const schema = this.eventSchemasByNode.get(nodeId);
-            return schema ? [schema.name] : [];
-        }
-        const eventNames = [];
-        for (const id of Array.from(relatedNodeIds)) {
-            const schema = this.eventSchemasByNode.get(id);
-            if (schema) {
-                eventNames.push(schema.name);
-            }
-        }
-        return eventNames;
-    }
-    /**
-     * Check if a node has event schema defined
-     * Supports both exact node IDs and base IDs (without numeric suffixes)
-     */
-    hasSchema(nodeId) {
-        // Check exact match first
-        if (this.eventSchemasByNode.has(nodeId)) {
-            return true;
-        }
-        // Check base ID pattern (e.g., "graph-converter" matches "graph-converter-1", etc.)
-        const baseId = nodeId.replace(/-\d+$/, '');
-        return this.nodeIdsByBaseId.has(baseId);
-    }
-}
-exports.EventValidator = EventValidator;
-/**
- * Create a validated event emitter for a specific node
- *
- * @example
- * ```typescript
- * const emit = createValidatedEmitter(validator, 'graph-converter', span);
- *
- * // Type-safe and runtime-validated
- * emit('conversion.started', {
- *   'config.nodeTypes': nodeTypes.length,
- *   'config.edgeTypes': edgeTypes.length
- * });
- * ```
- */
-function createValidatedEmitter(validator, nodeId, addEventFn, options = {}) {
-    return (eventName, attributes) => {
-        // Validate against schema
-        const result = validator.validate(nodeId, eventName, attributes);
-        if (!result.valid) {
-            if (options.strict !== false) {
-                // Strict mode: throw on validation errors
-                throw new EventValidationError(eventName, nodeId, result.errors);
-            }
-            else {
-                // Permissive mode: log warnings but allow the event
-                console.warn(`Event validation warnings for '${eventName}' on node '${nodeId}':`, result.errors);
-            }
-        }
-        // Emit the event
-        addEventFn(eventName, attributes);
-    };
-}
-exports.createValidatedEmitter = createValidatedEmitter;
-//# sourceMappingURL=event-validator.js.map

package/dist/telemetry/event-validator.js.map

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

package/dist/types/audit.d.ts

@@ -1,236 +0,0 @@
-/**
- * Log Audit Types
- *
- * Types for tracking log coverage, detecting orphaned logs, and generating
- * audit reports. Used to analyze how well a canvas maps to actual system logs.
- *
- * @see docs/CANVAS_LOG_ASSOCIATION.md for full audit documentation
- */
-import type { OtelResource } from './otel';
-/**
- * Status of a node based on log activity
- *
- * - `active`: Node is receiving logs normally
- * - `silent`: Node is defined but receiving no logs (may indicate misconfiguration)
- * - `error-heavy`: Node has unusually high error rate
- */
-export type NodeActivityStatus = 'active' | 'silent' | 'error-heavy';
-/**
- * Activity record for a single node
- *
- * Tracks log counts and health status for audit reporting.
- */
-export interface NodeActivity {
-    /** Node identifier */
-    nodeId: string;
-    /** Total log count during audit period */
-    logCount: number;
-    /** Error log count (severity >= ERROR) */
-    errorCount: number;
-    /** Warning log count (severity == WARN) */
-    warnCount: number;
-    /** Timestamp of last received log (null if never seen) */
-    lastSeen: number | null;
-    /** Computed activity status */
-    status: NodeActivityStatus;
-}
-/**
- * Suggested action for orphaned logs
- *
- * - `add-node`: Log appears legitimate, add a node to the canvas
- * - `fix-instrumentation`: Resource attributes look wrong, fix the source
- * - `remove`: Log appears to be test/debug artifact, should be removed
- * - `investigate`: Unable to determine, needs manual investigation
- */
-export type OrphanSuggestedAction = 'add-node' | 'fix-instrumentation' | 'remove' | 'investigate';
-/**
- * An orphaned log group
- *
- * Logs that matched the canvas scope but didn't match any node's
- * resourceMatch criteria. Grouped by resource signature.
- */
-export interface OrphanedLog {
-    /**
-     * Resource attributes from the orphaned logs
-     *
-     * This is the "signature" used to group similar orphans.
-     * Contains the key attributes that could be used for matching.
-     */
-    resource: OtelResource;
-    /** Number of logs with this resource signature */
-    count: number;
-    /**
-     * Sample log bodies for debugging
-     *
-     * Limited by audit config's maxSamplesPerOrphan setting.
-     */
-    samples: string[];
-    /** First seen timestamp */
-    firstSeen: number;
-    /** Last seen timestamp */
-    lastSeen: number;
-    /**
-     * Suggested action based on heuristics
-     *
-     * Determined by analyzing the resource attributes and log patterns.
-     */
-    suggestedAction: OrphanSuggestedAction;
-    /**
-     * Reason for the suggested action
-     *
-     * Human-readable explanation of why this action was suggested.
-     */
-    suggestedReason?: string;
-}
-/**
- * Type of audit recommendation
- *
- * - `add-node`: Add a new node to handle orphaned logs
- * - `remove-node`: Remove a node that's always silent
- * - `fix-match`: Update a node's resourceMatch criteria
- * - `check-instrumentation`: Verify OTEL instrumentation on source service
- */
-export type AuditRecommendationType = 'add-node' | 'remove-node' | 'fix-match' | 'check-instrumentation';
-/**
- * Priority level for recommendations
- */
-export type AuditRecommendationPriority = 'high' | 'medium' | 'low';
-/**
- * Audit recommendation
- *
- * Actionable suggestion generated from audit analysis.
- */
-export interface AuditRecommendation {
-    /** Type of recommendation */
-    type: AuditRecommendationType;
-    /** Target node ID or resource signature */
-    target: string;
-    /** Human-readable reason for this recommendation */
-    reason: string;
-    /** Priority level */
-    priority: AuditRecommendationPriority;
-    /**
-     * Suggested configuration snippet (if applicable)
-     *
-     * For `add-node` recommendations, this may contain a suggested
-     * resourceMatch configuration.
-     */
-    suggestedConfig?: Record<string, unknown>;
-}
-/**
- * Complete audit report for a canvas
- *
- * Generated by the AuditCollector after analyzing log routing data.
- *
- * @example
- * ```typescript
- * const report: AuditReport = {
- *   canvasId: 'checkout-system',
- *   generatedAt: Date.now(),
- *   period: {
- *     start: Date.now() - 86400000,  // 24h ago
- *     end: Date.now()
- *   },
- *   summary: {
- *     totalLogs: 45231,
- *     mappedLogs: 42108,
- *     orphanedLogs: 3123,
- *     coveragePercent: 93.1
- *   },
- *   nodeActivity: [...],
- *   orphans: [...],
- *   recommendations: [...]
- * };
- * ```
- */
-export interface AuditReport {
-    /** Canvas ID this report is for */
-    canvasId: string;
-    /** When this report was generated */
-    generatedAt: number;
-    /** Time period covered by this report */
-    period: {
-        start: number;
-        end: number;
-    };
-    /** Summary statistics */
-    summary: {
-        /** Total logs in scope during period */
-        totalLogs: number;
-        /** Logs successfully routed to a node */
-        mappedLogs: number;
-        /** Logs in scope but not matching any node */
-        orphanedLogs: number;
-        /** Coverage percentage (mappedLogs / totalLogs * 100) */
-        coveragePercent: number;
-        /** Number of out-of-scope logs (for reference) */
-        outOfScopeLogs?: number;
-    };
-    /** Per-node activity breakdown */
-    nodeActivity: NodeActivity[];
-    /** Orphaned log groups (grouped by resource signature) */
-    orphans: OrphanedLog[];
-    /** Actionable recommendations */
-    recommendations: AuditRecommendation[];
-    /** Warnings generated during audit */
-    warnings?: string[];
-}
-/**
- * Result of routing a single log
- *
- * Used for real-time routing decisions and audit tracking.
- */
-export interface LogRoutingResult {
-    /**
-     * Routing outcome
-     *
-     * - `routed`: Log matched a node
-     * - `orphaned`: Log in scope but no node match
-     * - `out-of-scope`: Log doesn't match canvas scope
-     */
-    status: 'routed' | 'orphaned' | 'out-of-scope';
-    /** Node ID the log was routed to (if status is 'routed') */
-    nodeId?: string;
-    /** Match specificity score (if status is 'routed') */
-    score?: number;
-    /** Resource signature (if status is 'orphaned') */
-    resource?: OtelResource;
-    /**
-     * Matching strategy used
-     *
-     * - `resource`: Matched via resourceMatch
-     * - `path`: Matched via sources (path-based)
-     * - `explicit`: Matched via explicit annotation in log
-     */
-    matchedBy?: 'resource' | 'path' | 'explicit';
-}
-/**
- * Event emitted when a log is orphaned
- *
- * Can be subscribed to for real-time orphan monitoring.
- */
-export interface OrphanEvent {
-    /** Timestamp of the orphan */
-    timestamp: number;
-    /** Resource attributes of the orphaned log */
-    resource: OtelResource;
-    /** Log body (truncated if too long) */
-    body: string;
-    /** Canvas ID where orphan was detected */
-    canvasId: string;
-}
-/**
- * Create a resource signature for grouping orphans
- *
- * Extracts key attributes that should be used for matching.
- * Two logs with the same signature are considered the same "type" of orphan.
- *
- * @param resource Full resource attributes
- * @returns Signature containing key matching attributes
- */
-export declare function createResourceSignature(resource: OtelResource): OtelResource;
-/**
- * Convert a resource signature to a string key for Map/Set usage
- */
-export declare function signatureToKey(resource: OtelResource): string;
-//# sourceMappingURL=audit.d.ts.map

package/dist/types/audit.d.ts.map

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

package/dist/types/audit.js

@@ -1,53 +0,0 @@
-"use strict";
-/**
- * Log Audit Types
- *
- * Types for tracking log coverage, detecting orphaned logs, and generating
- * audit reports. Used to analyze how well a canvas maps to actual system logs.
- *
- * @see docs/CANVAS_LOG_ASSOCIATION.md for full audit documentation
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.signatureToKey = exports.createResourceSignature = void 0;
-/**
- * Create a resource signature for grouping orphans
- *
- * Extracts key attributes that should be used for matching.
- * Two logs with the same signature are considered the same "type" of orphan.
- *
- * @param resource Full resource attributes
- * @returns Signature containing key matching attributes
- */
-function createResourceSignature(resource) {
-    // Extract key attributes that would typically be used for node matching
-    const signatureKeys = [
-        'service.name',
-        'service.namespace',
-        'deployment.environment',
-        'db.system',
-        'db.name',
-        'k8s.deployment.name',
-        'k8s.namespace.name',
-        'messaging.system',
-        'messaging.destination.name',
-    ];
-    const signature = {};
-    for (const key of signatureKeys) {
-        if (resource[key] !== undefined) {
-            signature[key] = resource[key];
-        }
-    }
-    return signature;
-}
-exports.createResourceSignature = createResourceSignature;
-/**
- * Convert a resource signature to a string key for Map/Set usage
- */
-function signatureToKey(resource) {
-    const entries = Object.entries(resource)
-        .filter(([, v]) => v !== undefined)
-        .sort(([a], [b]) => a.localeCompare(b));
-    return entries.map(([k, v]) => `${k}=${v}`).join('|');
-}
-exports.signatureToKey = signatureToKey;
-//# sourceMappingURL=audit.js.map

package/dist/types/audit.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/types/audit.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAuQH;;;;;;;;GAQG;AACH,SAAgB,uBAAuB,CAAC,QAAsB;IAC5D,wEAAwE;IACxE,MAAM,aAAa,GAAG;QACpB,cAAc;QACd,mBAAmB;QACnB,wBAAwB;QACxB,WAAW;QACX,SAAS;QACT,qBAAqB;QACrB,oBAAoB;QACpB,kBAAkB;QAClB,4BAA4B;KAC7B,CAAC;IAEF,MAAM,SAAS,GAAiB,EAAE,CAAC;IAEnC,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE;QAC/B,IAAI,QAAQ,CAAC,GAAG,CAAC,KAAK,SAAS,EAAE;YAC/B,SAAS,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;SAChC;KACF;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAvBD,0DAuBC;AAED;;GAEG;AACH,SAAgB,cAAc,CAAC,QAAsB;IACnD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC;SACrC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC;SAClC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IAE1C,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxD,CAAC;AAND,wCAMC"}

package/dist/types/auxiliary.d.ts

@@ -1,54 +0,0 @@
-/**
- * Auxiliary Manifest Types
- *
- * The auxiliary manifest catalogs project regions that are *not* OTEL scopes —
- * folders like `docs/` or `.github/` that support the project but don't emit
- * telemetry. Scope paths and area paths together form a partition of the
- * accounted-for filesystem.
- *
- * The manifest is open-ended: `areas` is the first section, but the top-level
- * shape leaves room for future sibling sections (e.g. external integrations)
- * without breaking the format.
- */
-/**
- * One project area — a folder (or file) that supports the project outside the
- * OTEL telemetry surface.
- */
-export interface ProjectArea {
-    /**
-     * Display name. Must be unique across all areas in the manifest — used as
-     * the area's identifier in diagnostics.
-     */
-    name: string;
-    /**
-     * One or more repo-relative paths owned by this area. Each entry may be a
-     * folder (covers all descendants) or a specific file. Paths must not
-     * overlap other areas, and must not overlap any scope path declared in a
-     * `.scopes.canvas`.
-     */
-    paths: string[];
-    /**
-     * Free-text purpose. The "light documentation" — a sentence about why this
-     * folder exists.
-     */
-    description: string;
-}
-/**
- * The full manifest document. Persisted at
- * `.principal-views/auxiliary.manifest.json`.
- */
-export interface AuxiliaryManifest {
-    /**
-     * Optional pointer to the JSON Schema that describes this file. Lets editors
-     * give autocomplete and validation when the field is set.
-     */
-    $schema?: string;
-    /** Project areas declared in this manifest. */
-    areas: ProjectArea[];
-}
-/**
- * Type guard: true when the value plausibly conforms to `AuxiliaryManifest`.
- * Shallow check — full validation lives in `AuxiliaryManifestValidator`.
- */
-export declare function isAuxiliaryManifest(value: unknown): value is AuxiliaryManifest;
-//# sourceMappingURL=auxiliary.d.ts.map

package/dist/types/auxiliary.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"auxiliary.d.ts","sourceRoot":"","sources":["../../src/types/auxiliary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAEhB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,+CAA+C;IAC/C,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAI9E"}

package/dist/types/auxiliary.js

@@ -1,27 +0,0 @@
-"use strict";
-/**
- * Auxiliary Manifest Types
- *
- * The auxiliary manifest catalogs project regions that are *not* OTEL scopes —
- * folders like `docs/` or `.github/` that support the project but don't emit
- * telemetry. Scope paths and area paths together form a partition of the
- * accounted-for filesystem.
- *
- * The manifest is open-ended: `areas` is the first section, but the top-level
- * shape leaves room for future sibling sections (e.g. external integrations)
- * without breaking the format.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.isAuxiliaryManifest = void 0;
-/**
- * Type guard: true when the value plausibly conforms to `AuxiliaryManifest`.
- * Shallow check — full validation lives in `AuxiliaryManifestValidator`.
- */
-function isAuxiliaryManifest(value) {
-    if (!value || typeof value !== 'object')
-        return false;
-    const v = value;
-    return Array.isArray(v.areas);
-}
-exports.isAuxiliaryManifest = isAuxiliaryManifest;
-//# sourceMappingURL=auxiliary.js.map

package/dist/types/auxiliary.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"auxiliary.js","sourceRoot":"","sources":["../../src/types/auxiliary.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AA2CH;;;GAGG;AACH,SAAgB,mBAAmB,CAAC,KAAc;IAChD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,CAAC,GAAG,KAA4B,CAAC;IACvC,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC;AAJD,kDAIC"}