@winkjs/composer 0.0.2 → 0.4.0

package/src/core/partition-manager/validate-flow.js

@@ -0,0 +1,157 @@
+// core/partition-manager/validate-flow.js
+
+/**
+ * @fileoverview Fail-fast validation of the `flow` object handed to
+ * partition-manager's `init()`.
+ *
+ * Three live callers construct this object:
+ *   - src/flow/run.js (production DSL — validated upstream)
+ *   - composer-website/apps/docs/lib/demo-runner.js (hand-constructed)
+ *   - composer-website/apps/docs/lib/benchmark-runner.js (hand-constructed)
+ *
+ * The last two bypass the DSL, so this module is their only contract
+ * enforcement point. Invalid shapes here used to surface as silent
+ * drops or late-throw errors on the first message; they now fail at
+ * flow start with an aggregated error list.
+ *
+ * Contract:
+ *   - partitionField        : null | non-empty string
+ *   - specializationField   : null | non-empty string
+ *   - specsBySpecialization : non-null object, ≥ 1 own key,
+ *                             each value is a non-empty array
+ *   - nodeModules           : non-null object
+ *   - yieldThreshold        : number ≥ 0 (Infinity accepted — the
+ *                             documented "never yield" sentinel used
+ *                             by website benchmark / demo runners)
+ *   - unknown top-level keys rejected (catches typos such as
+ *     `yieldThreshhold: 100` that would otherwise silently disable
+ *     yielding through a NaN comparison)
+ *
+ * Stricter checks (e.g. identifier-shape field names) are delegated to
+ * the flow DSL. Partition-manager's guard is defence-in-depth, not a
+ * re-implementation.
+ */
+
+import { validateWithSchema, validators } from '../utils/validate/index.js';
+
+// Keys accepted at the top level. Anything else is rejected as a typo
+// via _propertyNames whitelist enforcement in validateWithSchema.
+const PROPERTY_NAMES = [
+    'partitionField',
+    'specializationField',
+    'specsBySpecialization',
+    'nodeModules',
+    'yieldThreshold'
+];
+
+/**
+ * Accepts `null` (documented single-partition / single-specialization
+ * sentinel) or a non-empty string (field name for `msg[field]` lookup).
+ *
+ * @param { * } v - Value under validation.
+ * @returns { boolean } True when shape is acceptable.
+ */
+const isNullOrNonEmptyString = function ( v ) {
+    return v === null || ( typeof v === 'string' && v.length > 0 );
+}; // isNullOrNonEmptyString()
+
+/**
+ * Accepts a plain object (not null, not array) that carries at least
+ * one own key, with every value being a non-empty array. This is the
+ * minimum shape the graph-build branch of `update()` depends on.
+ *
+ * @param { * } v - Value under validation.
+ * @returns { boolean } True when shape is acceptable.
+ */
+const isNonNullObjectWithSpecArrays = function ( v ) {
+    if ( v === null ) {
+        return false;
+    }
+    if ( typeof v !== 'object' ) {
+        return false;
+    }
+    if ( Array.isArray( v ) ) {
+        return false;
+    }
+    const keys = Object.keys( v );
+    if ( keys.length === 0 ) {
+        return false;
+    }
+    for ( let i = 0; i < keys.length; i += 1 ) {
+        const specs = v[ keys[ i ] ];
+        if ( !Array.isArray( specs ) ) {
+            return false;
+        }
+        if ( specs.length === 0 ) {
+            return false;
+        }
+    }
+    return true;
+}; // isNonNullObjectWithSpecArrays()
+
+// Schema consumed by validateWithSchema. Fields that accept null do
+// not carry a `type` so that the schema framework's custom validator
+// runs for null values (the framework short-circuits type validators
+// ahead of custom ones only when type is set and fails).
+const flowSchema = {
+    partitionField: {
+        required: true,
+        validator: isNullOrNonEmptyString,
+        error: 'partitionField must be null or a non-empty string'
+    },
+    specializationField: {
+        required: true,
+        validator: isNullOrNonEmptyString,
+        error: 'specializationField must be null or a non-empty string'
+    },
+    specsBySpecialization: {
+        required: true,
+        validator: isNonNullObjectWithSpecArrays,
+        error: 'specsBySpecialization must be a non-null object with at least one specialization, each mapping to a non-empty spec array'
+    },
+    nodeModules: {
+        type: 'object',
+        required: true,
+        error: 'nodeModules must be a non-null object'
+    },
+    yieldThreshold: {
+        type: 'number',
+        required: true,
+        validator: validators.nonNegative,
+        error: 'yieldThreshold must be a number >= 0 (Infinity allowed)'
+    },
+    _propertyNames: PROPERTY_NAMES
+};
+
+/**
+ * Validates the flow config and throws TypeError on any violation.
+ * The error message aggregates every problem found, not just the first.
+ *
+ * @param { * } flow - Flow config object.
+ * @throws { TypeError } With aggregated error list on any violation.
+ */
+const validateFlow = function ( flow ) {
+    // Pre-check: validateWithSchema iterates `key in object`, which
+    // throws on null/undefined and behaves oddly on arrays. Handle
+    // those root-level shape errors up front with the same error
+    // format throwIfInvalid uses for consistency.
+    if ( flow === null || flow === undefined || typeof flow !== 'object' || Array.isArray( flow ) ) {
+        let actualType;
+        if ( flow === null ) {
+            actualType = 'null';
+        } else if ( Array.isArray( flow ) ) {
+            actualType = 'array';
+        } else {
+            actualType = typeof flow;
+        }
+        throw new TypeError(
+            `WinkComposer/partitionManager validation failed:\n  flow: Expected object, got ${actualType}`
+        );
+    }
+
+    const validation = validateWithSchema( flowSchema, flow, 'flow' );
+    validation.throwIfInvalid( 'partitionManager' );
+}; // validateFlow()
+
+export default validateFlow;
+export { validateFlow };

package/src/core/semantics/digest.js

@@ -0,0 +1,128 @@
+// core/semantics/digest.js
+
+/**
+ * @fileoverview Semantic Digest Computation
+ *
+ * Computes deterministic hashes of semantics for SSOT verification.
+ * Used by QuestDB storage layer for schema-semantics binding.
+ *
+ * Hash properties:
+ * - Formatting-independent (canonicalized before hashing)
+ * - Sorted object keys (deterministic)
+ * - Preserved array order (contexts are first-match-wins)
+ * - Includes descriptions (affect interpretation)
+ * - Hashes as-loaded (JSON files are the contract)
+ *
+ * Performance: Runs once at startup. Allocation-minimized for hot path
+ * is not a concern here.
+ *
+ * @see docs/architecture/storage-layer.md
+ */
+
+import crypto from 'node:crypto';
+
+/**
+ * Check if value is a plain object (not array, null, or other type).
+ *
+ * @param {*} value - Value to check
+ * @returns {boolean} True if plain object
+ */
+const isPlainObject = function ( value ) {
+    return (
+        typeof value === 'object' &&
+        value !== null &&
+        Array.isArray( value ) === false
+    );
+}; // isPlainObject()
+
+/**
+ * Recursively canonicalize a value for deterministic hashing.
+ * - Objects: keys sorted alphabetically, values canonicalized
+ * - Arrays: order preserved, elements canonicalized
+ * - Primitives: returned as-is
+ *
+ * @param {*} value - Value to canonicalize
+ * @returns {*} Canonicalized value
+ */
+const canonicalize = function ( value ) {
+    if ( Array.isArray( value ) ) {
+        const len = value.length;
+        const out = new Array( len );
+        for ( let i = 0; i < len; i += 1 ) {
+            out[ i ] = canonicalize( value[ i ] );
+        }
+        return out;
+    }
+
+    if ( isPlainObject( value ) ) {
+        const keys = Object.keys( value ).sort();
+        const out = Object.create( null );
+        for ( let i = 0; i < keys.length; i += 1 ) {
+            const key = keys[ i ];
+            out[ key ] = canonicalize( value[ key ] );
+        }
+        return out;
+    }
+
+    return value;
+}; // canonicalize()
+
+/**
+ * Compute SHA-256 hash of a string.
+ *
+ * @param {string} str - String to hash
+ * @returns {string} 64-character hex hash
+ */
+const sha256 = function ( str ) {
+    return crypto
+        .createHash( 'sha256' )
+        .update( str, 'utf8' )
+        .digest( 'hex' );
+}; // sha256()
+
+/**
+ * Compute semantic digest with global and per-asset-class hashes.
+ *
+ * @param {Object} semantics - { enums, assetClasses } after validation
+ * @param {string} [version] - Human-controlled version string
+ * @returns {Object} Digest with globalHash, enumsHash, assetHashes, version
+ */
+const computeSemanticsDigest = function ( semantics, version = '1.0.0' ) {
+    const { enums, assetClasses } = semantics;
+
+    // Canonicalize entire semantics for global hash
+    const canonical = canonicalize( { enums, assetClasses } );
+    const globalHash = sha256( JSON.stringify( canonical ) );
+
+    // Canonicalize enums only
+    const enumsHash = sha256( JSON.stringify( canonicalize( enums ) ) );
+
+    // Canonicalize each asset class individually
+    const assetHashes = Object.create( null );
+    const assetNames = Object.keys( assetClasses ).sort();
+    for ( let i = 0; i < assetNames.length; i += 1 ) {
+        const name = assetNames[ i ];
+        const canonicalAsset = canonicalize( assetClasses[ name ] );
+        assetHashes[ name ] = sha256( JSON.stringify( canonicalAsset ) );
+    }
+
+    return {
+        globalHash,
+        enumsHash,
+        assetHashes,
+        version
+    };
+}; // computeSemanticsDigest()
+
+// ============================================================================
+// EXPORTS
+// ============================================================================
+
+export {
+    canonicalize,
+    sha256,
+    computeSemanticsDigest,
+    isPlainObject
+};
+
+export default computeSemanticsDigest;

package/src/core/semantics/index.js

@@ -0,0 +1,83 @@
+// core/semantics/index.js
+
+/**
+ * @fileoverview Semantics Layer for @winkjs/composer
+ *
+ * Provides semantic metadata for columns, asset classes, and insight types.
+ * Loaded from JSON configuration files and used for:
+ * - Column validation (physicalRange, operational limits)
+ * - Data projection (insightType → column subset)
+ * - Threshold configuration (context-dependent limits)
+ * - LLM/dashboard context (units, descriptions)
+ *
+ * Usage:
+ * ```javascript
+ * import { loadSemantics } from './core/semantics/index.js';
+ *
+ * const semantics = await loadSemantics( './config/semantics' );
+ * const { enums, assetClasses } = semantics;
+ * ```
+ */
+
+// ============================================================================
+// LOADER
+// ============================================================================
+
+export {
+    loadSemantics,
+    loadEnums,
+    loadAssetClasses,
+    loadJsonFile,
+    validateCrossReferences
+} from './loader.js';
+
+// ============================================================================
+// DIGEST
+// ============================================================================
+
+export {
+    computeSemanticsDigest,
+    canonicalize
+} from './digest.js';
+
+// ============================================================================
+// WARNINGS
+// ============================================================================
+
+export {
+    WARNING_PREFIX,
+    defaultOnWarning,
+    createWarningCollector
+} from './warnings.js';
+
+// ============================================================================
+// SCHEMAS
+// ============================================================================
+
+export {
+    // Enum schema
+    enumSchema,
+    validEnumKeys,
+    validEnumValues,
+
+    // Column schema
+    columnSchema,
+    validPhysicalRange,
+    validOperational,
+    validSpecification,
+    validWhen,
+    validContext,
+    validContexts,
+    validColumnType,
+    validInterpretation,
+    validLimitsMutualExclusivity,
+    COLUMN_TYPES,
+    COLUMN_DEFAULTS,
+
+    // Asset class schema
+    assetClassSchema,
+    insightTypeSchema,
+    validColumnsStructure,
+    validInsightType,
+    validInsightTypes
+} from './schemas/index.js';