@holoscript/std 7.0.0 → 7.0.1

package/src/traits/SimulationLabTraits.ts

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

@@ -1,326 +0,0 @@
-/**
- * @fileoverview VRR (Virtual Reality Reality) Trait Definitions
- * @module @holoscript/std/traits
- *
- * 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_TASKS.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

@@ -1,8 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import * as ARTraits from '../ARTraits.js';
-
-describe('ARTraits', () => {
-  it('should export AR primitives if any', () => {
-    expect(ARTraits).toBeDefined();
-  });
-});

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

@@ -1,14 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import * as ecPrims from '../EconomicPrimitives.js';
-
-describe('EconomicPrimitives', () => {
-  it('should have calculating helpers', () => {
-    expect(ecPrims.calculateDepreciation).toBeDefined();
-    expect(ecPrims.calculateDepreciation(1.0, 0.0001, 0)).toBe(1.0);
-  });
-
-  it('should export bonding curve formulas', () => {
-    expect(ecPrims.bondingCurvePrice).toBeDefined();
-    expect(ecPrims.bondingCurvePrice(10, 1.0, 2.0, 'linear')).toBe(10);
-  });
-});

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

@@ -1,16 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { EconomicTraits, getEconomicTraitNames } from '../EconomicTraits.js';
-
-describe('EconomicTraits', () => {
-  it('should export standard economic traits', () => {
-    expect(EconomicTraits).toBeDefined();
-    expect(EconomicTraits.tradeable).toBeDefined();
-    expect(EconomicTraits.depreciating).toBeDefined();
-  });
-
-  it('should allow getting trait names', () => {
-    const names = getEconomicTraitNames();
-    expect(names).toContain('@tradeable');
-    expect(names.length).toBeGreaterThan(0);
-  });
-});