@mindot/will 0.1.0

package/src/extensions/time.ext.ts

@@ -0,0 +1,339 @@
+// ─────────────────────────────────────────────────────────────
+// src/extensions/time.ext.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Time extension for logistics, mobility, IoT, and smart home scenarios.
+ * These are NOT part of core — they layer on top.
+ */
+
+import type { SimulationClock } from '#core/clock'
+import type { Timestamp } from '#core/types'
+
+// ── Time-of-day utilities ─────────────────────────────────
+
+export interface TimeOfDay {
+  hour: number
+  minute: number
+  second: number
+  millisecond: number
+}
+
+export interface DateComponents {
+  year: number
+  month: number
+  day: number
+  hour: number
+  minute: number
+  second: number
+  millisecond: number
+  dayOfWeek: number  // 0 = Sunday, 6 = Saturday
+  timestamp: Timestamp
+}
+
+export interface TimeWindow {
+  startHour: number      // 0-23
+  endHour: number        // 0-23, can wrap (e.g., 22-6 for overnight)
+  startMinute?: number   // 0-59
+  endMinute?: number     // 0-59
+}
+
+export class TimeExtension {
+  private _clock: SimulationClock
+  private _timezoneOffset: number  // minutes from UTC, e.g., -480 for PST
+  // private _referenceDate: Date
+
+  constructor( clock: SimulationClock, timezoneOffsetMinutes: number = 0 ){
+    this._clock = clock
+    this._timezoneOffset = timezoneOffsetMinutes
+    // this._referenceDate = new Date( this._clock.now )
+  }
+
+  // ── Time-of-day (no date) ───────────────────────────────
+
+  getTimeOfDay(): TimeOfDay {
+    const date = this._getDateWithOffset()
+    
+    return {
+      hour: date.getHours(),
+      minute: date.getMinutes(),
+      second: date.getSeconds(),
+      millisecond: date.getMilliseconds()
+    }
+  }
+
+  getHour(): number {
+    return this._getDateWithOffset().getHours()
+  }
+
+  getMinute(): number {
+    return this._getDateWithOffset().getMinutes()
+  }
+
+  isBetweenHours( startHour: number, endHour: number ): boolean {
+    const hour = this.getHour()
+    
+    // Handle overnight windows (e.g., 22-6)
+    if( startHour > endHour )
+      return hour >= startHour || hour <= endHour
+    
+    return hour >= startHour && hour <= endHour
+  }
+
+  isWithinTimeWindow( window: TimeWindow ): boolean {
+    const
+    hour = this.getHour(),
+    minute = this.getMinute(),
+
+    currentMinutes = hour * 60 + minute,
+    startMinutes = ( window.startHour * 60 ) + ( window.startMinute ?? 0 ),
+    endMinutes = ( window.endHour * 60 ) + ( window.endMinute ?? 0 )
+    
+    // Handle overnight windows
+    if( startMinutes > endMinutes )
+      return currentMinutes >= startMinutes || currentMinutes <= endMinutes
+    
+    return currentMinutes >= startMinutes && currentMinutes <= endMinutes
+  }
+
+  // ── Full date/time (for scheduling) ─────────────────────
+
+  getCurrentDateComponents(): DateComponents {
+    const date = this._getDateWithOffset()
+    
+    return {
+      year: date.getFullYear(),
+      month: date.getMonth(),
+      day: date.getDate(),
+      hour: date.getHours(),
+      minute: date.getMinutes(),
+      second: date.getSeconds(),
+      millisecond: date.getMilliseconds(),
+      dayOfWeek: date.getDay(),
+      timestamp: this._clock.now
+    }
+  }
+
+  // ── Business hours / shift detection ────────────────────
+
+  isBusinessHours( 
+    businessStartHour: number = 9, 
+    businessEndHour: number = 17,
+    includeWeekends: boolean = false
+  ): boolean {
+    const
+    components = this.getCurrentDateComponents(),
+    isWeekend = components.dayOfWeek === 0 || components.dayOfWeek === 6
+    
+    if( !includeWeekends && isWeekend ) return false
+    
+    return this.isBetweenHours( businessStartHour, businessEndHour )
+  }
+
+  isRushHour( cityType: 'urban' | 'suburban' | 'rural' = 'urban'): boolean {
+    const hour = this.getHour()
+    
+    switch( cityType ) {
+      case 'urban':
+        // Morning: 7-9, Evening: 16-19
+        return ( hour >= 7 && hour <= 9 ) || ( hour >= 16 && hour <= 19 )
+      
+      case 'suburban':
+        // Morning: 6-8, Evening: 17-19
+        return ( hour >= 6 && hour <= 8 ) || ( hour >= 17 && hour <= 19 )
+      
+      case 'rural':
+        // Minimal rush hour
+        return ( hour >= 7 && hour <= 8 ) || ( hour >= 17 && hour <= 18 )
+      
+      default: return false
+    }
+  }
+
+  // ── Day part detection (for smart home) ─────────────────
+
+  getDayPart(): 'dawn' | 'morning' | 'afternoon' | 'evening' | 'night' | 'late-night' {
+    const hour = this.getHour()
+    
+    if( hour >= 5 && hour < 7 ) return 'dawn'
+    if( hour >= 7 && hour < 12 ) return 'morning'
+    if( hour >= 12 && hour < 17 ) return 'afternoon'
+    if( hour >= 17 && hour < 21 ) return 'evening'
+    if( hour >= 21 && hour < 24 ) return 'night'
+    return 'late-night'
+  }
+
+  // ── ETA with time-of-day adjustment (logistics) ─────────
+
+  calculateAdjustedEta( 
+    baseMinutes: number, 
+    trafficMultiplier: number = 1.0
+  ): number {
+    let multiplier = trafficMultiplier
+    
+    // Apply rush hour penalty
+    if( this.isRushHour() ) multiplier *= 1.5
+    
+    // Apply night time bonus (less traffic)
+    const hour = this.getHour()
+    if( hour >= 22 || hour <= 5 ) multiplier *= 0.8
+    
+    return baseMinutes * multiplier
+  }
+
+  // ── Scheduling helpers ──────────────────────────────────
+
+  getMinutesUntil( targetHour: number, targetMinute: number = 0 ): number {
+    const
+    current = this.getTimeOfDay(),
+    currentMinutes = current.hour * 60 + current.minute,
+    targetMinutes = targetHour * 60 + targetMinute
+    
+    if( targetMinutes > currentMinutes )
+      return targetMinutes - currentMinutes
+    
+    // Target is tomorrow
+    return ( 24 * 60 - currentMinutes ) + targetMinutes
+  }
+
+  getNextOccurrence( 
+    targetHour: number, 
+    targetMinute: number = 0,
+    onlyFuture: boolean = true
+  ): { minutesFromNow: number; timestamp: Timestamp } {
+    const
+    current = this.getTimeOfDay(),
+    currentMinutes = current.hour * 60 + current.minute,
+    targetMinutes = targetHour * 60 + targetMinute,
+    msPerMinute = 60 * 1000
+    
+    let minutesDelta: number
+    if( targetMinutes > currentMinutes )
+      minutesDelta = targetMinutes - currentMinutes
+    
+    else if( onlyFuture )
+      minutesDelta = ( 24 * 60 - currentMinutes ) + targetMinutes
+
+    else minutesDelta = targetMinutes - currentMinutes
+    
+    const wallDeltaMs = this._clock.toWallMs( minutesDelta * 60 * 1000 )
+    
+    return {
+      minutesFromNow: minutesDelta,
+      timestamp: Date.now() + wallDeltaMs
+    }
+  }
+
+  // ── Private helpers ─────────────────────────────────────
+
+  private _getDateWithOffset(): Date {
+    const
+    simTime = this._clock.now,
+    offsetMs = this._timezoneOffset * 60 * 1000
+
+    return new Date( simTime + offsetMs )
+  }
+
+  // ── Convenience factory ─────────────────────────────────
+
+  static forTimezone( clock: SimulationClock, timezone: string ): TimeExtension {
+    // NOTE: Full IANA timezone support requires a library like 'luxon'
+    // For now, uses local system timezone
+    const offsetMinutes = -new Date().getTimezoneOffset()
+    // In production, use Intl.DateTimeFormat or a library like 'luxon' for IANA conversion
+    return new TimeExtension( clock, offsetMinutes )
+  }
+}
+
+// ── Scenario helpers for time-based tests ─────────────────
+
+export interface TimeScenarioConfig {
+  startHour?: number
+  startMinute?: number
+  timeMultiplier?: number
+  timezone?: string
+}
+
+export class TimeScenarioHelper {
+  private _clock: SimulationClock
+  private _extension: TimeExtension
+
+  constructor( clock: SimulationClock, config: TimeScenarioConfig = {} ){
+    this._clock = clock
+    
+    // Set initial time if specified
+    if( config.startHour !== undefined ) {
+      const startDate = new Date( this._clock.now )
+
+      startDate.setHours( config.startHour, config.startMinute ?? 0, 0, 0 )
+      this._clock.setTime( startDate.getTime() )
+    }
+    
+    if( config.timeMultiplier )
+      this._clock.setMultiplier( config.timeMultiplier )
+    
+    this._extension = config.timezone 
+                        ? TimeExtension.forTimezone( this._clock, config.timezone )
+                        : new TimeExtension( this._clock, -new Date().getTimezoneOffset() )
+  }
+
+  get clock(): SimulationClock { return this._clock }
+  get time(): TimeExtension { return this._extension }
+
+  // Fast-forward simulation to a specific time of day
+  async advanceToTimeOfDay( 
+    targetHour: number, 
+    targetMinute: number = 0,
+    maxWaitMs: number = 30000  // 30 seconds real-time max
+  ): Promise<void> {
+    const
+    { minutesFromNow } = this._extension.getNextOccurrence( targetHour, targetMinute ),
+    waitWallMs = this._clock.toWallMs( minutesFromNow * 60 * 1000 )
+    
+    if( waitWallMs > maxWaitMs )
+      throw new Error(`Target time would require waiting ${waitWallMs}ms, exceeds max ${maxWaitMs}ms`)
+    
+    await this._clock.simSleep( minutesFromNow * 60 * 1000 )
+  }
+}
+
+// Usage Examples
+// Logistics: Time-of-day for delivery windows
+// typescript
+// import { DefaultSimulationClock } from './core/clock'
+// import { TimeExtension } from './extension/time.ext'
+
+// const clock = new DefaultSimulationClock({ timeScale: 60 }) // 1 real sec = 1 sim minute
+// clock.startTicks()
+
+// const timeExt = new TimeExtension( clock, -480 ) // PST
+
+// // Check if within delivery window
+// const isWithinWindow = timeExt.isWithinTimeWindow({
+//   startHour: 9,
+//   endHour: 17,
+//   startMinute: 0,
+//   endMinute: 0
+// })
+
+// // Adjust ETA for rush hour
+// const baseEta = 30 // minutes
+// const adjustedEta = timeExt.calculateAdjustedEta( baseEta, 1.2 )
+// Smart Home: Day part detection
+// typescript
+// const dayPart = timeExt.getDayPart()
+
+// switch( dayPart ) {
+//   case 'dawn':
+//     // Gradually increase lights
+//     break
+//   case 'night':
+//     // Arm security system, turn off non-essential devices
+//     break
+// }
+// Mobility: Rush hour detection
+// typescript
+// if( timeExt.isRushHour('urban') ) {
+//   // Reroute to avoid congested areas
+//   // Increase surge pricing
+// }

package/src/index.ts

@@ -0,0 +1,91 @@
+// ─────────────────────────────────────────────────────────────
+// src/index.ts  —  Will public API
+// ─────────────────────────────────────────────────────────────
+
+// Core simulation primitives (includes StorageAdapter, BunStorageAdapter, etc.)
+export * from '#core/index'
+
+// All cognitive engines
+export * from '#cognition/index'
+
+// Public types (OutboxMessage, effectorInvocation, ActionRequest, ActionResult, etc.)
+export * from '#types'
+
+// Deployment layer — WillStem, WillConfig, WillSummary, CognitiveHealth, TickListener …
+export {
+  WillStem,
+  type WillInstance,
+  type WillSummary,
+  type CognitiveHealth,
+  type WillStatus,
+  type TickListener,
+  type SimulationEventListener,
+  type StateSnapshot,
+  OUTBOX_TTL_TICKS,
+} from '#stem/index'
+
+export { assembleMind, type WillConfig } from '#stem/mind'
+
+// External transport — the unified bidirectional envelope channel between a Will
+// and its host peer (backend). Exposes the transport interface, every envelope
+// type, and the three implementations:
+//   • SocketIoTransport — production (Will = client, backend hosts the server)
+//   • StreamTransport    — live in-process consumer (per-channel demux via on())
+//   • LoopbackTransport  — deterministic in-memory transport for tests/replay
+export * from '#stem/tracts/transport/index'
+
+// Vector memory — semantic episodic recall. Exposes the adapter, the VectorIndex
+// interface, and the embedders so a host can inject a custom backend (e.g.
+// pgvector) via WillConfig.vectorMemoryAdapter. (EmbeddingProvider / VectorRecord
+// / VectorQueryResult / VectorQueryFilter are already exported via #cognition.)
+export {
+  DefaultVectorMemoryAdapter,
+  type VectorMemoryAdapter,
+  type VectorIndex,
+  OpenAICompatibleEmbedder,
+  MockEmbedder,
+  type EmbeddingProvider,
+  type VectorRecord,
+  type VectorQueryResult,
+  type VectorQueryFilter,
+  type VectorMemoryConfig,
+} from '#cognition/memory/index'
+
+// Profile registry — built-in profiles are auto-registered when this package is imported
+// (mind.ts imports '#profiles/built-in' as a side effect).
+export { resolveProfile, listProfiles, type WorldProfile } from '#profiles/index'
+
+// PMA (Personal Mind Archive) snapshot types
+export type {
+  PMASnapshot,
+  PMAIdentity,
+  PMABelief,
+  PMAGoal,
+  PMAEmotionalBaseline,
+  PMABehavioral,
+} from '#pma/index'
+
+// PMA eval harness — behavioral fidelity scoring
+export { PMAEvalHarness } from '#pma/eval'
+export type {
+  ReconstructionFidelityReport,
+  ReconstructionFidelityScores,
+  BehavioralProbeResult,
+  PMAProbe,
+} from '#pma/eval'
+
+// Sensory input types — used by callers of WillManager.ingestText()
+export type { TextMessage, VoiceChunk, SensoryInput } from '#senses/index'
+
+// ── SDK facade — the ergonomic embedding API (recommended entry point) ──
+// `Will.create()` wraps WillStem in the shape a developer expects: on('message'),
+// effector(name, handler), say(), state(), hibernate()/wake(). Drop to `.stem`
+// for the full contract. See src/sdk/will.ts + examples/effectors.ts.
+export { Will } from '#sdk/will'
+export type {
+  CreateWillOptions,
+  WillMessage,
+  WillStateSummary,
+  EffectorHandler,
+  EffectorResult,
+} from '#sdk/will'

package/src/llm/gate.ts

@@ -0,0 +1,140 @@
+// ─────────────────────────────────────────────────────────────
+// src/llm/gate.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Global concurrency gate for all LLM calls.
+*
+ * Two protections:
+ *   1. Semaphore — caps simultaneous in-flight requests so independent
+ *      engines (decision, semantic, planning…) can run in parallel up to
+ *      the concurrency limit without flooding the API.
+ *   2. Retry with exponential backoff — on 429 the call waits and retries.
+ *
+ * No minimum interval is enforced.  A fixed inter-call floor causes
+ * starvation: every engine serialises into a single queue and slower
+ * engines (semantic integrator) never get a timely slot because faster
+ * engines (decision) keep resetting the clock.  The retry mechanism is
+ * the right tool for actual rate-limit overages.
+ *
+ * Configured via env vars:
+ *   WILL_LLM_CONCURRENCY    max simultaneous LLM calls (default 2)
+ *   WILL_LLM_MAX_RETRIES    retries before giving up on a 429 (default 4)
+ *   WILL_LLM_RETRY_BASE_MS  first retry wait, doubles each attempt (default 2000)
+ */
+
+import { logger } from '#core/logger'
+
+const MAX_CONCURRENT = parseInt( process.env.WILL_LLM_CONCURRENCY ?? '2')
+
+// Read lazily (per retry, not per module load) so tests and live tuning can
+// adjust the backoff without re-importing the module. Jitter scales with the
+// base delay (base/2 ⇒ up to 1000 ms at the 2000 ms default — unchanged).
+const maxRetries  = () => parseInt( process.env.WILL_LLM_MAX_RETRIES   ?? '4')
+const baseDelayMs = () => parseInt( process.env.WILL_LLM_RETRY_BASE_MS ?? '2000')
+
+// ── Semaphore ─────────────────────────────────────────────────
+
+export class LLMSemaphore {
+  private _running = 0
+  private readonly _max: number
+  private _queue: Array<() => void> = []
+
+  constructor( max: number ){ this._max = max }
+
+  async acquire(): Promise<() => void> {
+    if( this._running < this._max ){
+      this._running++
+      return this._release()
+    }
+
+    // No free slot — wait until one is handed off directly to us. The releasing
+    // call transfers its slot without decrementing _running, so we must NOT
+    // increment here: we already own the slot the moment we resume.
+    await new Promise<void>( resolve => this._queue.push( resolve ) )
+    return this._release()
+  }
+
+  private _release(): () => void {
+    let done = false
+    return () => {
+      if( done ) return
+      done = true
+
+      // Hand the slot directly to the next waiter, keeping _running unchanged so
+      // a concurrent acquire() can't slip into a transient gap and over-admit
+      // past _max. Only decrement when nobody is waiting.
+      const next = this._queue.shift()
+      if( next ) next()
+      else this._running--
+    }
+  }
+
+  get running(): number { return this._running }
+  get queued():  number { return this._queue.length }
+}
+
+export const llmGate = new LLMSemaphore( MAX_CONCURRENT )
+
+// ── Rate-limit detection ──────────────────────────────────────
+
+export function isRateLimitError( err: unknown ): boolean {
+  if( !( err instanceof Error ) ) return false
+  const msg = err.message
+
+  return (
+    msg.includes('rate_limit_error')          ||
+    ( err as { statusCode?: number } ).statusCode === 429 ||
+    msg.includes('rate limit')                ||
+    msg.includes('429')
+  )
+}
+
+// ── Gate + retry wrapper ──────────────────────────────────────
+
+/**
+ * Run `fn` through the global semaphore with automatic 429 retry.
+ *
+ * - Waits for a slot before calling `fn`
+ * - On 429: releases the slot, waits (exponential backoff + jitter), retries
+ * - Throws after MAX_RETRIES exhausted, or for non-retryable errors
+ */
+export async function withGate<T>(
+  fn: () => Promise<T>,
+  label: string,
+  gate: LLMSemaphore = llmGate
+): Promise<T> {
+  let attempt = 0
+
+  // eslint-disable-next-line no-constant-condition
+  while( true ){
+    const release = await gate.acquire()
+    let retryDelay: number | null = null
+
+    try {
+      const result = await fn()
+      return result
+    }
+    catch( err ){
+      if( isRateLimitError( err ) && attempt < maxRetries() ){
+        attempt++
+        const base = baseDelayMs()
+        retryDelay = Math.min(
+          60_000,
+          base * Math.pow( 2, attempt ) + Math.random() * ( base / 2 )
+        )
+      }
+      else throw err
+    }
+    finally { release() }
+
+    // Slot released in `finally` above — the backoff wait happens OUTSIDE the
+    // slot-holding region, so a rate-limited call no longer starves the other
+    // engines of concurrency while it sleeps.
+    logger.warn(
+      `[LLMGate] ${label} rate limited — retry ${attempt}/${maxRetries()} in ${Math.round( retryDelay! )}ms` +
+      `  (running=${gate.running} queued=${gate.queued})`
+    )
+    await new Promise( r => setTimeout( r, retryDelay! ) )
+  }
+}