@mindot/will 0.1.0

package/src/cognition/faculties/planning.engine/plan.frontier.ts

@@ -0,0 +1,83 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/faculties/planning.engine/plan.frontier.ts — the ready frontier
+// ─────────────────────────────────────────────────────────────
+//
+// Planning-as-prior's mechanical heart: resolve the prerequisite DAG to find the
+// ready frontier, and project active steps as transient `plan.prior` entities the
+// AffordanceSynthesizer turns into competing affordances. A prior BIASES the one
+// action competition — it never dispatches (see the engine header).
+//
+// Pure functions over (plan, state) — no engine state, no bus. Extracted
+// verbatim from planning.engine.ts; behavior identical.
+// ─────────────────────────────────────────────────────────────
+
+import type { Tick, ReadonlySimulationState, StateCommands } from '#core/types'
+import { clamp01, type Plan, type PlanStep } from '#faculties/planning.engine/types'
+
+/** Steps whose prerequisites are all completed/skipped — ready to activate. */
+export function computeReadySet( plan: Plan ): PlanStep[] {
+  const ready: PlanStep[] = []
+
+  for( const step of plan.steps ){
+    if( step.status !== 'pending' ) continue
+
+    const allPrereqsSatisfied = step.prerequisites.every( prereqId => {
+      const prereqStep = plan.steps.find( s => s.id === prereqId )
+      return prereqStep && ( prereqStep.status === 'completed' || prereqStep.status === 'skipped' )
+    } )
+
+    allPrereqsSatisfied && ready.push( step )
+  }
+
+  return ready
+}
+
+/**
+ * Project every executing plan's active frontier as transient `plan.prior`
+ * entities — the top-down bias the AffordanceSynthesizer reads. Rebuilt each tick
+ * (cleared then re-emitted, like the affordance field), so a frontier that
+ * advances or a plan that ends stops biasing automatically. The prior carries the
+ * planId/stepId provenance that flows affordance → intent → action.outcome, and a
+ * `planBias` strength from the goal's importance ⊕ the plan's confidence. It never
+ * forces an action — if a more pressing affordance wins, the plan re-projects next
+ * tick (no orphaning).
+ */
+export function projectFrontier(
+  plans:        Iterable<Plan>,
+  commands:     StateCommands,
+  tick:         Tick,
+  state:        ReadonlySimulationState,
+  goalPriority: ( goalId: string ) => number,
+  biasGain:     number,
+): void {
+  // Clear the previous tick's priors — they are transient.
+  for( const [ id, e ] of state.entities )
+    if( e.type === 'plan.prior' ) commands.delete!.push( id )
+
+  for( const plan of plans ){
+    if( plan.status !== 'executing' ) continue
+
+    // Channel A: conscientiousness develops `planBiasGain` UP, so a conscientious
+    // Will pushes its plan's frontier harder against competing impulses.
+    const strength = clamp01( ( 0.5 * goalPriority( plan.goalId ) + 0.5 * plan.confidence ) * biasGain )
+
+    for( const step of plan.steps ){
+      if( step.status !== 'active' ) continue
+      commands.set!.push({
+        // tick in the id (like the affordance field) so this tick's fresh prior
+        // never collides with last tick's cleared one in the same command batch.
+        id:   `plan-prior-${ tick }-${ plan.id }-${ step.id }`,
+        type: 'plan.prior',
+        metadata: {
+          schema:         step.action,        // advisory suggested schema (not dispatched)
+          planId:         plan.id,
+          stepId:         step.id,
+          planBias:       strength,
+          targetEntityId: step.targetEntityId,
+          parameters:     {},
+          tick,
+        },
+      })
+    }
+  }
+}

package/src/cognition/faculties/planning.engine/plan.store.ts

@@ -0,0 +1,174 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/faculties/planning.engine/plan.store.ts — canonical plan state
+// ─────────────────────────────────────────────────────────────
+//
+// Owns every map the engine used to hold: the canonical plan store, the
+// goal-scoped index (P4: multiple plans per goal), terminal bookkeeping
+// (persist-once + retention GC — P5), and the id counter. Pure state +
+// deterministic bookkeeping; no bus, no facets, no LLM.
+//
+// Extracted verbatim from planning.engine.ts — behavior identical.
+// ─────────────────────────────────────────────────────────────
+
+import type { Tick, StateCommands } from '#core/types'
+import { TERMINAL_STATUSES, type Plan } from '#faculties/planning.engine/types'
+
+export class PlanStore {
+  /**
+   * Canonical plan store, keyed by plan.id ("plan-N") — the id the execution,
+   * outcome (`action.outcome.planId`) and facet paths all use.
+   */
+  private _plans = new Map<string, Plan>()
+  /**
+   * Secondary index goalId → ordered plan.ids (creation order). Multiple plans
+   * per goal supported (P4); terminal plans stay in the list as history and are
+   * filtered out by activePlanForGoal. Goal-scoped reads route through the
+   * helpers below.
+   */
+  private _planByGoal = new Map<string, string[]>()
+  /**
+   * Plan ids already persisted in a terminal state. Terminal plans never change
+   * again, so they are persisted once and then skipped by persist() — avoids
+   * unbounded state-write amplification as completed/failed plans accumulate. (P5)
+   */
+  private _persistedTerminal = new Set<string>()
+  /** planId → sim tick it became terminal; drives retention GC (gcTerminal). */
+  private _terminalAt = new Map<string, number>()
+  private _planCounter = 0
+
+  // ── Reads ──────────────────────────────────────────────────
+
+  get size(): number { return this._plans.size }
+
+  get( planId: string ): Plan | undefined { return this._plans.get( planId ) }
+  has( planId: string ): boolean          { return this._plans.has( planId ) }
+  all(): IterableIterator<Plan>           { return this._plans.values() }
+
+  isTerminal( plan: Plan ): boolean { return TERMINAL_STATUSES.includes( plan.status ) }
+
+  /** All plans for a goal, in creation order (any status). */
+  plansForGoal( goalId: string ): Plan[] {
+    const ids = this._planByGoal.get( goalId )
+    if( !ids ) return []
+    const out: Plan[] = []
+    for( const id of ids ){
+      const p = this._plans.get( id )
+      if( p ) out.push( p )
+    }
+    return out
+  }
+
+  /** The most-recently-created non-terminal plan for a goal, if any. */
+  activePlanForGoal( goalId: string ): Plan | undefined {
+    const all = this.plansForGoal( goalId )
+    for( let i = all.length - 1; i >= 0; i-- )
+      if( !TERMINAL_STATUSES.includes( all[ i ]!.status ) ) return all[ i ]
+    return undefined
+  }
+
+  /**
+   * Resolve which plan an executive plan-op targets. Prefers an explicit
+   * `planId` (must belong to the same goal); otherwise falls back to the goal's
+   * active plan. Returns undefined when neither resolves (caller may create one).
+   */
+  resolveIngestTarget( goalId: string, planId?: string ): Plan | undefined {
+    if( planId ){
+      const p = this._plans.get( planId )
+      if( p && p.goalId === goalId ) return p
+    }
+    return this.activePlanForGoal( goalId )
+  }
+
+  // ── Writes ─────────────────────────────────────────────────
+
+  /** Next sequential plan id ("plan-N") — deterministic, never PRNG. */
+  nextId(): string {
+    this._planCounter++
+    return `plan-${this._planCounter}`
+  }
+
+  /** Register a plan in both the canonical store and the goal index. */
+  index( plan: Plan ): void {
+    this._plans.set( plan.id, plan )
+    const ids = this._planByGoal.get( plan.goalId ) ?? []
+    ids.push( plan.id )
+    this._planByGoal.set( plan.goalId, ids )
+  }
+
+  /** Record the tick a plan entered a terminal status (drives retention GC). */
+  markTerminal( planId: string, tick: number ): void {
+    this._terminalAt.set( planId, tick )
+  }
+
+  // ── Retention GC ───────────────────────────────────────────
+
+  /**
+   * Evict terminal plans (and delete their state entity) once they've been
+   * terminal longer than the retention window. Terminal plans never change, so
+   * retaining them forever accretes memory + state entities on a long-lived mind.
+   * Deterministic: the window is compared against sim ticks (R2-safe).
+   * `onEvict` lets the engine tear down any facet still keyed to the plan.
+   */
+  gcTerminal( tick: Tick, commands: StateCommands, retentionTicks: number, onEvict: ( planId: string ) => void ): void {
+    const now = tick as unknown as number
+    let evicted = 0
+
+    for( const [ id, plan ] of this._plans ){
+      if( !TERMINAL_STATUSES.includes( plan.status ) ) continue
+      const since = this._terminalAt.get( id ) ?? now
+      if( now - since <= retentionTicks ) continue
+
+      this._plans.delete( id )
+      this._persistedTerminal.delete( id )
+      this._terminalAt.delete( id )
+      onEvict( id )   // safety — a terminal plan shouldn't still hold a facet
+
+      const ids = this._planByGoal.get( plan.goalId )
+      if( ids ){
+        const next = ids.filter( x => x !== id )
+        if( next.length ) this._planByGoal.set( plan.goalId, next )
+        else              this._planByGoal.delete( plan.goalId )
+      }
+
+      commands.delete!.push( id )
+      evicted++
+    }
+
+    if( evicted > 0 )
+      commands.metrics!.push( [ 'planning.plans_evicted', evicted ] )
+  }
+
+  // ── Persistence ────────────────────────────────────────────
+
+  persist( commands: StateCommands, tick: Tick ): void {
+    for( const plan of this._plans.values() ){
+      // Terminal plans never change again — persist once (in their terminal state)
+      // then skip, so completed/failed/rejected plans don't re-serialize every
+      // tick forever (unbounded write amplification on long sessions). (P5)
+      const terminal = TERMINAL_STATUSES.includes( plan.status )
+      if( terminal && this._persistedTerminal.has( plan.id ) ) continue
+
+      commands.set!.push( {
+        id: plan.id, type: 'plan',
+        createdAt: plan.createdAt, updatedAt: tick,
+        metadata: {
+          goalId: plan.goalId,
+          steps: plan.steps.map( s => ( {
+            id: s.id, order: s.order, action: s.action,
+            description: s.description, expectedOutcome: s.expectedOutcome,
+            prerequisites: s.prerequisites, estimatedDuration: s.estimatedDuration,
+            status: s.status, outcome: s.outcome,
+          } ) ),
+          estimatedCost: plan.estimatedCost, confidence: plan.confidence,
+          status: plan.status, executionTier: plan.executionTier,
+          expectedOutcome: plan.expectedOutcome,
+          requestingEntityId: plan.requestingEntityId,
+          requestingThreadId: plan.requestingThreadId,
+          source: 'planning-engine'
+        }
+      } )
+
+      if( terminal ) this._persistedTerminal.add( plan.id )
+    }
+  }
+}