@holoscript/std 2.1.0 → 6.0.3

package/src/traits/SimulationLabTraits.ts

@@ -0,0 +1,191 @@
+/**
+ * @fileoverview SimulationLab Trait Definition for HoloScript
+ * @module @holoscript/std/traits
+ *
+ * Defines the @simulation_lab trait that enables hypothesis testing
+ * on any HoloScript composition. Attach this trait to run parameter sweeps,
+ * collect metrics across N epochs, and produce statistical results.
+ *
+ * Composes with all economic traits for economy stress testing.
+ *
+ * @version 1.0.0
+ * @category simulation
+ */
+
+import type { TraitDefinition } from '../types.js';
+
+/**
+ * Extended trait definition with simulation-specific metadata.
+ */
+export interface SimulationTraitDefinition extends TraitDefinition {
+  /** Compiler hints for batch execution */
+  compiler_hints?: {
+    requires_runtime?: string[];
+    thread_safety?: 'main_thread' | 'worker_thread' | 'any';
+    performance_budget_ms?: number;
+    batch_mode?: boolean;
+  };
+  /** Which economic/VR traits this composes with */
+  composesWith: string[];
+}
+
+// =============================================================================
+// TRAIT DEFINITION
+// =============================================================================
+
+/**
+ * The SimulationLab trait.
+ */
+export const SimulationLabTraits: Record<string, SimulationTraitDefinition> = {
+  simulation_lab: {
+    name: '@simulation_lab',
+    description:
+      'Attaches scientific hypothesis testing to any HoloScript composition. ' +
+      'Enables parameter sweeps, multi-epoch execution, statistical analysis, ' +
+      'and exportable results. The universe gets one sample — HoloScript gives ' +
+      'you infinite. Results are marketplace-sellable as verified simulation data.',
+    params: {
+      hypothesis: {
+        type: 'string',
+        required: true,
+        description: 'Human-readable hypothesis description.',
+      },
+      null_hypothesis: {
+        type: 'string',
+        required: false,
+        default: '',
+        description: 'Formal null hypothesis (H0). Auto-generated if empty.',
+      },
+      alternative_hypothesis: {
+        type: 'string',
+        required: false,
+        default: '',
+        description: 'Formal alternative hypothesis (H1). Auto-generated if empty.',
+      },
+      direction: {
+        type: 'string',
+        required: false,
+        default: 'different',
+        description: 'Expected direction of effect: greater | less | different | equal.',
+      },
+      epochs: {
+        type: 'number',
+        required: false,
+        default: 1000,
+        description: 'Number of simulation runs per parameter combination. More = higher power.',
+      },
+      seed_start: {
+        type: 'number',
+        required: false,
+        default: 0,
+        description: 'Starting seed for reproducibility. Seeds increment per epoch.',
+      },
+      confidence_level: {
+        type: 'number',
+        required: false,
+        default: 0.95,
+        description: 'Confidence level for statistical tests (0.0 - 1.0). Default 0.95 = α=0.05.',
+      },
+      metrics: {
+        type: 'string[]',
+        required: true,
+        description:
+          'List of metric names to collect each epoch. Must match emitted metric events.',
+      },
+      statistical_test: {
+        type: 'string',
+        required: false,
+        default: 'auto',
+        description:
+          'Statistical test to use: t_test | mann_whitney_u | chi_squared | auto. ' +
+          'Auto selects based on data distribution.',
+      },
+      export_training_data: {
+        type: 'boolean',
+        required: false,
+        default: false,
+        description: 'Whether to export results as training data for DataForge pipeline.',
+      },
+      marketplace_publishable: {
+        type: 'boolean',
+        required: false,
+        default: false,
+        description:
+          'Whether to package results for marketplace listing as verified simulation data.',
+      },
+      max_duration_ms: {
+        type: 'number',
+        required: false,
+        default: 300000,
+        description:
+          'Maximum wall-clock time for the entire experiment (5 min default). ' +
+          'Prevents runaway simulations.',
+      },
+      worker_count: {
+        type: 'number',
+        required: false,
+        default: 4,
+        description: 'Number of parallel workers for epoch execution.',
+      },
+    },
+    validator: (params) => {
+      if (!params.hypothesis || typeof params.hypothesis !== 'string') return false;
+      if (!params.metrics || !Array.isArray(params.metrics) || params.metrics.length === 0)
+        return false;
+      if (params.epochs !== undefined && (params.epochs < 1 || params.epochs > 1000000))
+        return false;
+      if (
+        params.confidence_level !== undefined &&
+        (params.confidence_level <= 0 || params.confidence_level >= 1)
+      )
+        return false;
+      if (params.direction !== undefined) {
+        if (!['greater', 'less', 'different', 'equal'].includes(params.direction)) return false;
+      }
+      if (params.statistical_test !== undefined) {
+        if (!['t_test', 'mann_whitney_u', 'chi_squared', 'auto'].includes(params.statistical_test))
+          return false;
+      }
+      return true;
+    },
+    composesWith: [
+      '@tradeable',
+      '@depreciating',
+      '@bonding_curved',
+      '@taxable_wealth',
+      '@pid_controlled',
+    ],
+    compiler_hints: {
+      requires_runtime: [
+        'SimulationRuntime.runExperiment',
+        'SimulationRuntime.collectMetrics',
+        'SimulationRuntime.runStatisticalTest',
+        'SimulationRuntime.exportResults',
+      ],
+      thread_safety: 'worker_thread',
+      performance_budget_ms: 300000, // Experiment budget, not per-frame
+      batch_mode: true,
+    },
+  },
+};
+
+// =============================================================================
+// TRAIT UTILITIES
+// =============================================================================
+
+/**
+ * Get all simulation trait names.
+ */
+export function getSimulationTraitNames(): string[] {
+  return Object.keys(SimulationLabTraits).map((k) => SimulationLabTraits[k].name);
+}
+
+/**
+ * Look up a simulation trait definition by name.
+ */
+export function getSimulationTrait(name: string): SimulationTraitDefinition | undefined {
+  const key = name.startsWith('@') ? name.slice(1) : name;
+  return SimulationLabTraits[key];
+}
+
+export default SimulationLabTraits;

package/src/traits/VRRTraits.ts

@@ -0,0 +1,326 @@
+/**
+ * @fileoverview VRR (Virtual Reality Reality) Trait Definitions
+ * @module @holoscript/std/traits
+ *
+ * TODO: HIGH - Define VRR Trait Library for 1:1 Digital Twins
+ *
+ * PURPOSE:
+ * Define standard HoloScript traits for VRR (Virtual Reality Reality) features:
+ * 1:1 real-world mirroring, geo-anchoring, real-time sync (weather, events,
+ * inventory), business quests, layer transitions, and x402 payments.
+ *
+ * VISION:
+ * Developers annotate HoloScript compositions with @vrr_twin, @weather_sync,
+ * @inventory_sync, and VRRCompiler auto-generates Three.js code with real-time
+ * API integration. Example: @weather_sync → auto-generates weather.gov API calls
+ * and scene fog/precipitation updates.
+ *
+ * REQUIREMENTS:
+ * 1. Core VRR Traits: @vrr_twin, @reality_mirror, @geo_anchor
+ * 2. Real-Time Sync Traits: @weather_sync, @event_sync, @inventory_sync, @traffic_sync
+ * 3. Business Traits: @quest_hub, @business_marker, @coupon_reward
+ * 4. Layer Transition Traits: @layer_shift, @ar_portal, @vr_portal
+ * 5. Payment Traits: @x402_paywall, @subscription, @revenue_share
+ * 6. Geo-Location Traits: @geo_coords, @geo_sync, @geo_fence
+ *
+ * EXAMPLE USAGE:
+ * ```holoscript
+ * composition "PhoenixDowntownVRR" {
+ *   zone#phoenix_downtown @vrr_twin @reality_mirror @geo_sync("phoenix_az_center") {
+ *     geo_coords: { lat: 33.4484, lng: -112.0740 }
+ *     weather_sync: @weather_sync { provider: "weather.gov", refresh: 5_minutes }
+ *     event_sync: @event_sync { provider: "eventbrite", refresh: 5_minutes }
+ *
+ *     business#phoenix_brew @quest_hub @inventory_sync @x402_paywall {
+ *       geo_coords: { lat: 33.4484, lng: -112.0740 }
+ *       inventory_api: @inventory_sync { provider: "square_pos", refresh: 1_minute }
+ *       paywall: @x402_paywall { price: 5_usdc, asset: "USDC", network: "base" }
+ *
+ *       quest "LatteLegend" @quest_hub {
+ *         steps: [
+ *           @ar_scan { location: "storefront_window" },
+ *           @vrr_find_item { item: "oat_milk", hint: "Check the fridge" },
+ *           @vr_taste_menu { menu_item: "oat_milk_latte" }
+ *         ]
+ *         reward: @coupon_reward { value: "Buy1Get1Free", expiry: 30_days }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * TRAIT DEFINITIONS:
+ *
+ * 1. @vrr_twin - Marks composition as VRR digital twin (1:1 real-world mirror)
+ *    - Example: @vrr_twin { mirror: "phoenix_downtown" }
+ *    - Compiler: Generates geo-anchored Three.js scene
+ *
+ * 2. @reality_mirror - Enables real-world synchronization
+ *    - Example: @reality_mirror { sync: ["weather", "events", "inventory"] }
+ *    - Compiler: Generates API integration code
+ *
+ * 3. @geo_anchor - Geo-location anchoring (lat/lng)
+ *    - Example: @geo_anchor { lat: 33.4484, lng: -112.0740 }
+ *    - Compiler: Converts lat/lng to scene coordinates
+ *
+ * 4. @weather_sync - Real-time weather synchronization
+ *    - Example: @weather_sync { provider: "weather.gov", refresh: 5_minutes }
+ *    - Compiler: Generates weather API polling code
+ *    - Runtime: Updates scene fog, precipitation, temperature
+ *
+ * 5. @event_sync - Real-time event synchronization
+ *    - Example: @event_sync { provider: "eventbrite", refresh: 5_minutes }
+ *    - Compiler: Generates event API polling code
+ *    - Runtime: Spawns NPC crowds, triggers quests on festivals
+ *
+ * 6. @inventory_sync - Real-time inventory synchronization
+ *    - Example: @inventory_sync { provider: "square_pos", refresh: 1_minute }
+ *    - Compiler: Generates POS API integration code
+ *    - Runtime: Enables/disables quests based on stock
+ *
+ * 7. @quest_hub - Marks business as quest starting point
+ *    - Example: @quest_hub { quests: ["latte_legend", "espresso_challenge"] }
+ *    - Compiler: Generates quest NPC, interaction prompts
+ *
+ * 8. @layer_shift - AR/VRR/VR layer transitions
+ *    - Example: @layer_shift { from: "ar", to: "vrr", price: 5_usdc }
+ *    - Compiler: Generates x402 payment + redirect logic
+ *    - Runtime: Persists state across layers (IndexedDB → Supabase)
+ *
+ * 9. @x402_paywall - HTTP 402 payment requirement
+ *    - Example: @x402_paywall { price: 5, asset: "USDC", network: "base" }
+ *    - Compiler: Generates 402 response + payment verification
+ *    - Runtime: Grants access after payment confirmed
+ *
+ * 10. @geo_sync - Geographic data synchronization
+ *     - Example: @geo_sync { center: "phoenix_az_center", radius: 5000 } // 5km
+ *     - Compiler: Fetches nearby POIs, traffic, events
+ *
+ * INTEGRATION POINTS:
+ * - VRRCompiler.ts (trait parsing, code generation)
+ * - VRRRuntime.ts (real-time sync implementation)
+ * - x402PaymentService.ts (payment verification)
+ * - BusinessQuestTools.ts (quest builder uses traits)
+ *
+ * RESEARCH REFERENCES:
+ * - HOLOLAND_INTEGRATION_TODOS.md (VRRTraits section)
+ * - VRRCompiler.ts (trait requirements)
+ * - uAA2++_Protocol/5.GROW P.029: "Machine Customers for VR Platforms"
+ *
+ * IMPLEMENTATION TASKS:
+ * [x] Define VRRTrait interface
+ * [ ] Implement @vrr_twin trait definition
+ * [ ] Implement @reality_mirror trait definition
+ * [ ] Implement @geo_anchor trait definition
+ * [ ] Implement @weather_sync trait definition
+ * [ ] Implement @event_sync trait definition
+ * [ ] Implement @inventory_sync trait definition
+ * [ ] Implement @quest_hub trait definition
+ * [ ] Implement @layer_shift trait definition
+ * [ ] Implement @x402_paywall trait definition
+ * [ ] Implement @geo_sync trait definition
+ * [ ] Add trait validation (ensure required params present)
+ * [ ] Add trait composition (combine multiple traits)
+ * [ ] Add tests (VRRTraits.test.ts)
+ * [ ] Add documentation (trait usage examples)
+ *
+ * ESTIMATED COMPLEXITY: 6/10 (medium - trait definitions, validation)
+ * ESTIMATED TIME: 1 week (includes testing, documentation)
+ * PRIORITY: HIGH (blocks VRRCompiler implementation)
+ *
+ * BLOCKED BY:
+ * - Nothing (can implement now)
+ *
+ * UNBLOCKS:
+ * - VRRCompiler.ts (trait parsing)
+ * - VRRRuntime.ts (trait-driven initialization)
+ * - BusinessQuestTools.ts (trait-based quest builder)
+ */
+
+import type { TraitDefinition } from '../types.js';
+
+export interface VRRTrait extends TraitDefinition {
+  name: string;
+  params: Record<string, any>;
+  validator?: (params: Record<string, any>) => boolean;
+  compiler_hints?: {
+    requires_runtime?: string[];
+    generates_api_calls?: string[];
+  };
+}
+
+export const VRRTraits: Record<string, VRRTrait> = {
+  vrr_twin: {
+    name: '@vrr_twin',
+    description: 'Marks composition as VRR digital twin (1:1 real-world mirror)',
+    params: {
+      mirror: { type: 'string', required: true, description: 'Real-world location to mirror' },
+    },
+    validator: (params) => !!params.mirror,
+    compiler_hints: {
+      generates_api_calls: ['geo_location'],
+    },
+  },
+
+  reality_mirror: {
+    name: '@reality_mirror',
+    description: 'Enables real-world synchronization (weather, events, inventory)',
+    params: {
+      sync: { type: 'array', required: true, description: 'List of sync types' },
+    },
+    validator: (params) => Array.isArray(params.sync) && params.sync.length > 0,
+  },
+
+  geo_anchor: {
+    name: '@geo_anchor',
+    description: 'Geo-location anchoring (lat/lng positioning)',
+    params: {
+      lat: { type: 'number', required: true, description: 'Latitude' },
+      lng: { type: 'number', required: true, description: 'Longitude' },
+    },
+    validator: (params) => {
+      return (
+        typeof params.lat === 'number' &&
+        typeof params.lng === 'number' &&
+        params.lat >= -90 &&
+        params.lat <= 90 &&
+        params.lng >= -180 &&
+        params.lng <= 180
+      );
+    },
+  },
+
+  weather_sync: {
+    name: '@weather_sync',
+    description: 'Real-time weather synchronization',
+    params: {
+      provider: { type: 'string', required: true, description: 'weather.gov | openweathermap' },
+      refresh: {
+        type: 'duration',
+        required: false,
+        default: '5_minutes',
+        description: 'Refresh interval',
+      },
+    },
+    validator: (params) => ['weather.gov', 'openweathermap'].includes(params.provider),
+    compiler_hints: {
+      requires_runtime: ['VRRRuntime.syncWeather'],
+      generates_api_calls: ['weather.gov', 'openweathermap'],
+    },
+  },
+
+  event_sync: {
+    name: '@event_sync',
+    description: 'Real-time event synchronization (festivals, concerts)',
+    params: {
+      provider: { type: 'string', required: true, description: 'eventbrite | ticketmaster' },
+      refresh: {
+        type: 'duration',
+        required: false,
+        default: '5_minutes',
+        description: 'Refresh interval',
+      },
+    },
+    validator: (params) => ['eventbrite', 'ticketmaster'].includes(params.provider),
+    compiler_hints: {
+      requires_runtime: ['VRRRuntime.syncEvents'],
+      generates_api_calls: ['eventbrite', 'ticketmaster'],
+    },
+  },
+
+  inventory_sync: {
+    name: '@inventory_sync',
+    description: 'Real-time inventory synchronization (Square POS, Shopify)',
+    params: {
+      provider: {
+        type: 'string',
+        required: true,
+        description: 'square_pos | shopify | woocommerce',
+      },
+      refresh: {
+        type: 'duration',
+        required: false,
+        default: '1_minute',
+        description: 'Refresh interval',
+      },
+      websocket: {
+        type: 'boolean',
+        required: false,
+        default: false,
+        description: 'Use WebSocket for real-time',
+      },
+    },
+    validator: (params) => ['square_pos', 'shopify', 'woocommerce'].includes(params.provider),
+    compiler_hints: {
+      requires_runtime: ['VRRRuntime.syncInventory'],
+      generates_api_calls: ['square_pos', 'shopify', 'woocommerce'],
+    },
+  },
+
+  quest_hub: {
+    name: '@quest_hub',
+    description: 'Marks business as quest starting point',
+    params: {
+      quests: { type: 'array', required: true, description: 'List of quest IDs' },
+    },
+    validator: (params) => Array.isArray(params.quests) && params.quests.length > 0,
+  },
+
+  layer_shift: {
+    name: '@layer_shift',
+    description: 'AR/VRR/VR layer transitions with state persistence',
+    params: {
+      from: { type: 'string', required: true, description: 'ar | vrr | vr' },
+      to: { type: 'string', required: true, description: 'ar | vrr | vr' },
+      price: { type: 'number', required: false, description: 'USDC price for transition' },
+      persist_state: {
+        type: 'boolean',
+        required: false,
+        default: true,
+        description: 'Persist state across layers',
+      },
+    },
+    validator: (params) => {
+      const validLayers = ['ar', 'vrr', 'vr'];
+      return validLayers.includes(params.from) && validLayers.includes(params.to);
+    },
+    compiler_hints: {
+      requires_runtime: ['VRRRuntime.persistState', 'ARRuntime.createARPortal'],
+    },
+  },
+
+  x402_paywall: {
+    name: '@x402_paywall',
+    description: 'HTTP 402 payment requirement for content access',
+    params: {
+      price: { type: 'number', required: true, description: 'Price in USDC' },
+      asset: { type: 'string', required: false, default: 'USDC', description: 'USDC | ETH | SOL' },
+      network: {
+        type: 'string',
+        required: false,
+        default: 'base',
+        description: 'base | ethereum | solana',
+      },
+    },
+    validator: (params) => {
+      return (
+        params.price > 0 &&
+        ['USDC', 'ETH', 'SOL'].includes(params.asset || 'USDC') &&
+        ['base', 'ethereum', 'solana'].includes(params.network || 'base')
+      );
+    },
+    compiler_hints: {
+      generates_api_calls: ['x402_payment_service'],
+    },
+  },
+
+  geo_sync: {
+    name: '@geo_sync',
+    description: 'Geographic data synchronization (POIs, traffic, events)',
+    params: {
+      center: { type: 'string', required: true, description: 'Center point identifier' },
+      radius: { type: 'number', required: false, default: 5000, description: 'Radius in meters' },
+    },
+    validator: (params) => !!params.center && (params.radius || 0) >= 0,
+  },
+};

package/src/traits/__tests__/ARTraits.test.ts

@@ -0,0 +1,14 @@
+import { describe, it, expect } from 'vitest';
+
+// Auto-generated test for ARTraits
+// Source: packages/std/src/traits/ARTraits.ts
+
+describe('ARTraits', () => {
+  it('should be defined', () => {
+    // TODO: Import and test ARTraits
+  });
+
+  it('should have basic functionality', () => {
+    // TODO: Add meaningful tests for ARTraits
+  });
+});

package/src/traits/__tests__/EconomicPrimitives.test.ts

@@ -0,0 +1,14 @@
+import { describe, it, expect } from 'vitest';
+
+// Auto-generated test for EconomicPrimitives
+// Source: packages/std/src/traits/EconomicPrimitives.ts
+
+describe('EconomicPrimitives', () => {
+  it('should be defined', () => {
+    // TODO: Import and test EconomicPrimitives
+  });
+
+  it('should have basic functionality', () => {
+    // TODO: Add meaningful tests for EconomicPrimitives
+  });
+});

package/src/traits/__tests__/EconomicTraits.test.ts

@@ -0,0 +1,14 @@
+import { describe, it, expect } from 'vitest';
+
+// Auto-generated test for EconomicTraits
+// Source: packages/std/src/traits/EconomicTraits.ts
+
+describe('EconomicTraits', () => {
+  it('should be defined', () => {
+    // TODO: Import and test EconomicTraits
+  });
+
+  it('should have basic functionality', () => {
+    // TODO: Add meaningful tests for EconomicTraits
+  });
+});

package/src/types.ts

@@ -346,20 +346,35 @@ export function parseColor(color: Color): ColorRGBA {
     const c = (1 - Math.abs(2 * l - 1)) * s;
     const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
     const m = l - c / 2;
-    let r = 0, g = 0, b = 0;
-
-    if (h < 60) { r = c; g = x; }
-    else if (h < 120) { r = x; g = c; }
-    else if (h < 180) { g = c; b = x; }
-    else if (h < 240) { g = x; b = c; }
-    else if (h < 300) { r = x; b = c; }
-    else { r = c; b = x; }
+    let r = 0,
+      g = 0,
+      b = 0;
+
+    if (h < 60) {
+      r = c;
+      g = x;
+    } else if (h < 120) {
+      r = x;
+      g = c;
+    } else if (h < 180) {
+      g = c;
+      b = x;
+    } else if (h < 240) {
+      g = x;
+      b = c;
+    } else if (h < 300) {
+      r = x;
+      b = c;
+    } else {
+      r = c;
+      b = x;
+    }
 
     return { r: r + m, g: g + m, b: b + m, a: 1 };
   }
 
   if ('a' in color) {
-    return color as ColorRGBA;
+    return color;
   }
 
   return { ...color, a: 1 };
@@ -369,8 +384,28 @@ export function parseColor(color: Color): ColorRGBA {
  * Color to hex string
  */
 export function colorToHex(color: ColorRGB | ColorRGBA): string {
-  const r = Math.round(color.r * 255).toString(16).padStart(2, '0');
-  const g = Math.round(color.g * 255).toString(16).padStart(2, '0');
-  const b = Math.round(color.b * 255).toString(16).padStart(2, '0');
+  const r = Math.round(color.r * 255)
+    .toString(16)
+    .padStart(2, '0');
+  const g = Math.round(color.g * 255)
+    .toString(16)
+    .padStart(2, '0');
+  const b = Math.round(color.b * 255)
+    .toString(16)
+    .padStart(2, '0');
   return `#${r}${g}${b}`;
 }
+
+// =============================================================================
+// TRAIT DEFINITIONS
+// =============================================================================
+
+export interface TraitDefinition {
+  name: string;
+  description?: string;
+  type?: string;
+  params?: Record<string, any>;
+  parameters?: Record<string, any>;
+  validator?: (params: Record<string, any>) => boolean;
+  validation?: any;
+}

package/std_error.log

@@ -0,0 +1,5 @@
+npm warn Unknown project config "shamefully-hoist". This will stop working in the next major version of npm.
+npm warn Unknown project config "strict-peer-dependencies". This will stop working in the next major version of npm.
+src/__tests__/SimulationLabPrimitives.test.ts(345,12): error TS18048: 'trait.params' is possibly 'undefined'.
+src/__tests__/SimulationLabPrimitives.test.ts(346,12): error TS18048: 'trait.params' is possibly 'undefined'.
+src/physics.ts(11,22): error TS2835: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './spatial.js'?

package/tsup.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: [
+    'src/index.ts',
+    'src/math.ts',
+    'src/collections.ts',
+    'src/string.ts',
+    'src/time.ts',
+    'src/traits/EconomicPrimitives.ts',
+    'src/traits/EconomicTraits.ts',
+  ],
+  format: ['esm', 'cjs'],
+  dts: false,
+  clean: true,
+  sourcemap: true,
+});

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    exclude: ['**/dist/**', '**/node_modules/**'],
+  },
+});