@mindot/will 0.5.0 → 0.7.0

package/src/stem/mind.ts

@@ -409,10 +409,10 @@ export function _resolveVectorMemory(
   const mockMode = process.env.WILL_VECTOR_MEMORY === 'mock'
   const rawModel = embeddingModel
     ?? process.env.WILL_EMBEDDING_MODEL
-    ?? ( process.env.WILL_EMBEDDING_API_KEY ? 'text-embedding-3-small' : 'none' )
+    ?? ( process.env.WILL_EMBEDDING_API_KEY ? 'text-embedding-3-small' : 'none')
 
   // Explicitly disabled — the documented "none" sentinel or recall turned off.
-  if( !mockMode && ( rawModel === 'none' || process.env.WILL_SEMANTIC_RECALL === 'false' ) )
+  if( !mockMode && ( rawModel === 'none' || process.env.WILL_SEMANTIC_RECALL === 'false') )
     return { embedder: null, vectorMemory: null }
 
   // testMode promises a deterministic, zero-key, offline mind — but a dev .env
@@ -581,9 +581,9 @@ export function assembleMind( willId: string, config: WillConfig ): MindAssembly
     profileContext: profile?.context,
   })
   if( !idGuard.ok )
-    throw new Error( `Invalid Will identity for "${willId}": ${ idGuard.errors.join( '; ' ) }` )
+    throw new Error(`Invalid Will identity for "${willId}": ${ idGuard.errors.join('; ') }`)
   for( const w of idGuard.warnings )
-    logger.warn( `[identity-guard] ${willId}: ${w}` )
+    logger.warn(`[identity-guard] ${willId}: ${w}`)
   config = { ...config, identity: idGuard.sanitized.identity }
 
   // ── Construct ────────────────────────────────────────────
@@ -602,8 +602,8 @@ export function assembleMind( willId: string, config: WillConfig ): MindAssembly
   // sessionLogger/grants); tests/unit/assembly.order.test.ts pins that set per
   // tier, so a NEW unwired attachment fails loudly in CI, not here.
   for( const rec of auditAssemblyWiring( simulation.orchestrator.engines ) )
-    if( rec.status === 'unwired' )
-      logger.debug( `[assembly] ${willId}: ${rec.engine}.${rec.method} unwired at assembly (anatomy=${anatomy})` )
+    if( rec.status === 'unwired')
+      logger.debug(`[assembly] ${willId}: ${rec.engine}.${rec.method} unwired at assembly (anatomy=${anatomy})`)
 
   // ── Seed readable simulation state ───────────────────────
   // Identity, optional initial goals, and the engine-config mirror.
@@ -772,7 +772,7 @@ function _constructCognition(
   // ── Planning Engine ──────────────────────────────────────
   const planningEngine = new PlanningEngine()
   planningEngine.attachGoalManager( goalManager )
-  if( anatomy !== 'reflex' ) planningEngine.attachExecutiveEngine( executiveEngine )
+  if( anatomy !== 'reflex') planningEngine.attachExecutiveEngine( executiveEngine )
   executiveEngine.attachPlanningEngine( planningEngine )
 
   // ── Executive ────────────────────────────────────────────
@@ -791,7 +791,7 @@ function _constructCognition(
   autobiographicalNarrator.attachEpisodicConsolidator( episodicConsolidator )
   autobiographicalNarrator.attachSemanticIntegrator( semanticIntegrator )
   // Satellites harvest the executive's own output — attach wherever it runs.
-  if( anatomy !== 'reflex' ){
+  if( anatomy !== 'reflex'){
     autobiographicalNarrator.attachExecutiveEngine( executiveEngine )
     introspectionEngine.attachExecutiveEngine( executiveEngine )
   }
@@ -807,7 +807,7 @@ function _constructCognition(
   empathySimulator.attachTheoryOfMind( theoryOfMind )
 
   // ── Context compaction components (mind anatomy only) ──
-  if( anatomy !== 'reflex' ){
+  if( anatomy !== 'reflex'){
     const summarizer = new ExecutiveSummarizer({
       summaryInterval:   parseInt( process.env.WILL_SUMMARY_INTERVAL   ?? '10'),
       bufferSize:        parseInt( process.env.WILL_SUMMARY_BUFFER_SIZE ?? '12'),
@@ -845,7 +845,7 @@ function _constructCognition(
   const olfactionEngine       = new OlfactionEngine()
   const gustationEngine       = new GustationEngine()
 
-  if( anatomy !== 'reflex' )
+  if( anatomy !== 'reflex')
     auditionEngine.attachExecutiveEngine( executiveEngine )
 
   // §5.4 — cold-spawn digest hydration: on the first turn for an entity, seed an
@@ -906,7 +906,7 @@ function _constructCognition(
   // winner (graceful System-1 degradation).
   const deliberationEngine = new DeliberationEngine()
   deliberationEngine.setWillName( config.name )
-  if( anatomy !== 'reflex' )
+  if( anatomy !== 'reflex')
     deliberationEngine.attachExecutive( executiveEngine )
 
   // ── Build Cognition ──────────────────────────────────────
@@ -1108,7 +1108,7 @@ function _seedIdentity(
   // to infer its identity from context. config.name is the canonical source of truth.
   const nameAlreadyInPrompt = personaText.toLowerCase().includes( config.name.toLowerCase() )
   const namePrefix = nameAlreadyInPrompt ? '' : `I am ${config.name}.`
-  const fullPersonaText = [ namePrefix, personaText ].filter( Boolean ).join( ' ' )
+  const fullPersonaText = [ namePrefix, personaText ].filter( Boolean ).join(' ')
 
   const prompt = [
     WILL_CORE_PREAMBLE,

package/src/stem/policy/arbiter.ts

@@ -0,0 +1,136 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/policy/arbiter.ts  —  the policy seam (PEP side)
+// ─────────────────────────────────────────────────────────────
+//
+// POLICY_REAFFERENCE P0. A Policy Decision Point is consulted before a
+// host-owned effector invocation is handed to the world. This file is the
+// *interface* only — the enforcement point lives in effectorController
+// (`bufferInvocation`), which is the single tract every external effect
+// already passes through.
+//
+// Deliberately provider-agnostic: no transport, no vendor types, no Go. The
+// null arbiter below is the default and is a strict no-op, so a Will with no
+// policy configured runs byte-identically to one built before this file
+// existed. `RuleTableArbiter` (rule.table.ts) is the local reference adapter;
+// an external PDP (e.g. helm-ai-kernel) is a later phase and must implement
+// nothing more than this interface.
+//
+// WHY THE STEM AND NOT COGNITION: the mind must never meet a permission
+// dialog. It dispatches an intent and the world either yields or resists —
+// a refusal arrives as reafference, in the same currency as any other
+// outcome. Keeping the arbiter below the SDK and outside the cognition layer
+// is what preserves that (and is the honest model besides: a body that
+// cannot do the thing).
+//
+// SYNC OR ASYNC: `evaluate` may return a Verdict or a Promise of one. An
+// external PDP will be async, and that is fine by construction — the intent
+// is already held 'awaiting' for AWAIT_TIMEOUT (15 ticks) by the executor, so
+// arbiter latency is absorbed by machinery that already exists. Both P0
+// adapters are synchronous, which is why P0 changes no behaviour.
+// ─────────────────────────────────────────────────────────────
+
+/** What the boundary decided about a proposed effect. */
+export type PolicyDecision = 'allow' | 'deny' | 'escalate'
+
+/**
+ * Is this denial a property of the ACTION CLASS (never permitted under the
+ * active policy) or of THIS INSTANCE (wrong target, exceeded bound)?
+ *
+ * This is the distinction that makes a refusal learnable rather than a wall to
+ * re-probe forever, and it is the field we are proposing upstream to HELM. A
+ * 'class' denial should suppress the affordance; an 'instance' denial should
+ * only narrow the parameter envelope the Will reaches for.
+ */
+export type DenialFinality = 'class' | 'instance'
+
+/**
+ * The nearest allowed envelope — what WOULD have been permitted. Structured so
+ * a learner can consume it; `field` names the constraint that bit.
+ *
+ * Every denial branch of a policy evaluator already computes this and usually
+ * discards it. We keep it.
+ */
+export interface PolicyCounterfactual {
+  /** The constrained field, e.g. 'ttl_days', 'target', 'amount'. */
+  field:      string
+  /** What the Will asked for. */
+  requested?: unknown
+  /** The bound or permitted set, e.g. 30, or [ 'a', 'b' ]. */
+  allowed?:   unknown
+}
+
+/** A boundary decision about one proposed invocation. */
+export interface Verdict {
+  decision:        PolicyDecision
+  /** Stable machine-readable code, e.g. 'TARGET_NOT_ALLOWED'. Never prose. */
+  reasonCode?:     string
+  /** Meaningful on 'deny' only. Absent ⇒ treat as 'instance' (the safe default:
+   *  it narrows rather than suppresses, so a mis-tagged denial cannot silently
+   *  delete an ability from the Will's reach). */
+  finality?:       DenialFinality
+  counterfactual?: PolicyCounterfactual
+  /** Free-text for logs and host UX. NEVER parsed by cognition. */
+  detail?:         string
+}
+
+/**
+ * The proposed effect, as the stem sees it. Mirrors the `agency.invocation`
+ * bus payload the MotorSchemaExecutor emits — no cognitive internals cross
+ * this boundary, only the act itself.
+ */
+export interface PolicyInvocation {
+  willId:          string
+  /** The awaiting `agency.intent` id — the correlation handle, end to end. */
+  intentId:        string
+  /** The motor schema id, i.e. the ability being enacted. */
+  schema:          string
+  parameters:      Record<string, unknown>
+  targetEntityId?: string
+  /** The ability's declared meaning, as given by the host at wiring time. */
+  description?:    string
+  tick:            number
+}
+
+/**
+ * A Policy Decision Point. Implementations must be PURE with respect to the
+ * Will: an arbiter may read its own policy and the invocation, and nothing
+ * else. It must not reach into simulation state.
+ *
+ * DETERMINISM CONTRACT: an arbiter is an external oracle, exactly like the LLM.
+ * Its verdicts are recorded on the tape and replayed back — replay never
+ * re-consults an arbiter (see P1). Implementations therefore need not be
+ * deterministic themselves, but MUST be free of side effects on the Will.
+ */
+export interface PolicyArbiter {
+  /** Stable identifier, recorded alongside the verdict for audit. */
+  readonly name: string
+  evaluate( invocation: PolicyInvocation ): Verdict | Promise<Verdict>
+}
+
+/** The single allow verdict, frozen and shared — the null arbiter allocates nothing. */
+const ALLOW: Readonly<Verdict> = Object.freeze({ decision: 'allow' as const })
+
+/**
+ * The default. Allows everything, allocates nothing, logs nothing.
+ *
+ * A Will running this must be byte-identical to one built before the policy
+ * seam existed — that property is asserted by test, and it is what lets this
+ * ship dark.
+ */
+export const NULL_ARBITER: PolicyArbiter = {
+  name: 'null',
+  evaluate(): Verdict { return ALLOW },
+}
+
+/** True when the arbiter is the no-op default (used to skip the seam entirely). */
+export function isNullArbiter( arbiter: PolicyArbiter | null | undefined ): boolean {
+  return !arbiter || arbiter === NULL_ARBITER
+}
+
+/**
+ * Normalize a denial's finality. Absent ⇒ 'instance', the conservative reading:
+ * an unlabelled refusal narrows the envelope but never removes the ability.
+ */
+export function finalityOf( verdict: Verdict ): DenialFinality {
+  return verdict.finality === 'class' ? 'class' : 'instance'
+}

package/src/stem/policy/rule.table.ts

@@ -0,0 +1,172 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/policy/rule.table.ts  —  the local reference PDP
+// ─────────────────────────────────────────────────────────────
+//
+// POLICY_REAFFERENCE P0. A declarative, in-process arbiter: enough policy to
+// prove the seam is sufficient WITHOUT an external dependency, and the
+// fallback if an external-PDP track stalls.
+//
+// It is also a working demonstration of the two receipt fields we are
+// proposing upstream (`finality`, `counterfactual`): when a bound is violated
+// this arbiter *returns what would have been allowed* instead of discarding
+// it. That is the whole argument, implemented in ~40 lines — a denial that
+// says "never" and one that says "not with these parameters" are different
+// facts, and a learner needs to tell them apart.
+//
+// Evaluation is first-match-wins over an ordered rule array, so a verdict is a
+// pure function of ( rules, invocation ) — no clock, no IO, no iteration-order
+// surprises. Deterministic by construction, which keeps replay honest.
+// ─────────────────────────────────────────────────────────────
+
+import type {
+  PolicyArbiter, PolicyInvocation, Verdict,
+  PolicyDecision, DenialFinality, PolicyCounterfactual,
+} from '#stem/policy/arbiter'
+
+/** A bound on one parameter. Checked in declaration order: max, min, equals, oneOf. */
+export interface ParamConstraint {
+  max?:    number
+  min?:    number
+  equals?: unknown
+  oneOf?:  readonly unknown[]
+}
+
+/**
+ * One rule. `schema`/`target` scope it (omitted ⇒ matches any); the FIRST rule
+ * whose scope matches decides, so order is policy.
+ *
+ * `require` is meaningful with `decision: 'allow'` only: the scope matched, and
+ * these constraints must hold for the allow to stand. A violation flips the
+ * verdict to deny — carrying the counterfactual — with finality 'instance',
+ * because the ability itself was permitted and only these arguments were not.
+ *
+ * A rule with `decision: 'deny'` and no `require` is a flat class-level ban;
+ * it reports finality 'class' unless told otherwise.
+ */
+export interface PolicyRule {
+  schema?:     string
+  target?:     string
+  decision:    PolicyDecision
+  require?:    Record<string, ParamConstraint>
+  reasonCode?: string
+  finality?:   DenialFinality
+}
+
+export interface RuleTableOptions {
+  rules: readonly PolicyRule[]
+  /**
+   * The verdict when NO rule matches. Required — deliberately not defaulted.
+   * A policy component that silently defaults open is a trap; make the posture
+   * an explicit decision at the call site. 'deny' is fail-closed and is the
+   * right choice once a rule set is complete.
+   */
+  fallthrough: PolicyDecision
+  /** Recorded with every verdict for audit. Defaults to 'rule-table'. */
+  name?: string
+}
+
+export class RuleTableArbiter implements PolicyArbiter {
+  readonly name: string
+  private readonly _rules:       readonly PolicyRule[]
+  private readonly _fallthrough: PolicyDecision
+
+  constructor( opts: RuleTableOptions ){
+    this.name         = opts.name ?? 'rule-table'
+    this._rules       = opts.rules
+    this._fallthrough = opts.fallthrough
+  }
+
+  evaluate( invocation: PolicyInvocation ): Verdict {
+    for( const rule of this._rules ){
+      if( !scopeMatches( rule, invocation ) ) continue
+
+      if( rule.decision !== 'allow')
+        return {
+          decision: rule.decision,
+          ...( rule.reasonCode ? { reasonCode: rule.reasonCode } : {} ),
+          ...( rule.decision === 'deny'
+            ? { finality: rule.finality ?? 'class' }
+            : {} ),
+        }
+
+      const violation = firstViolation( rule.require, invocation.parameters )
+      if( violation )
+        return {
+          decision:       'deny',
+          reasonCode:     rule.reasonCode ?? violation.reasonCode,
+          finality:       rule.finality ?? 'instance',
+          counterfactual: violation.counterfactual,
+        }
+
+      return { decision: 'allow' }
+    }
+
+    return {
+      decision: this._fallthrough,
+      ...( this._fallthrough !== 'allow' ? { reasonCode: 'NO_MATCHING_RULE', finality: 'class' as const } : {} ),
+    }
+  }
+}
+
+// ── matching ─────────────────────────────────────────────────────────────────
+
+function scopeMatches( rule: PolicyRule, inv: PolicyInvocation ): boolean {
+  if( rule.schema !== undefined && rule.schema !== '*' && rule.schema !== inv.schema ) return false
+  if( rule.target !== undefined && rule.target !== '*' && rule.target !== inv.targetEntityId ) return false
+  return true
+}
+
+interface Violation {
+  reasonCode:     string
+  counterfactual: PolicyCounterfactual
+}
+
+/**
+ * The first constraint that fails, in declared order — so the counterfactual a
+ * caller receives is stable, not whichever check happened to run first.
+ *
+ * An ABSENT parameter is a violation: a bound cannot be honoured by a value
+ * that was never supplied, and habitual enaction (which carries no args) must
+ * not slip past a constraint the deliberate path would have to satisfy.
+ */
+function firstViolation(
+  require:    Record<string, ParamConstraint> | undefined,
+  parameters: Record<string, unknown>,
+): Violation | null {
+  if( !require ) return null
+
+  for( const [ field, constraint ] of Object.entries( require ) ){
+    const present = Object.prototype.hasOwnProperty.call( parameters, field )
+    if( !present )
+      return {
+        reasonCode:     'PARAM_MISSING',
+        counterfactual: { field, allowed: describe( constraint ) },
+      }
+
+    const value = parameters[ field ]
+
+    if( constraint.max !== undefined && !( typeof value === 'number' && value <= constraint.max ) )
+      return { reasonCode: 'PARAM_ABOVE_MAX', counterfactual: { field, requested: value, allowed: constraint.max } }
+
+    if( constraint.min !== undefined && !( typeof value === 'number' && value >= constraint.min ) )
+      return { reasonCode: 'PARAM_BELOW_MIN', counterfactual: { field, requested: value, allowed: constraint.min } }
+
+    if( 'equals' in constraint && value !== constraint.equals )
+      return { reasonCode: 'PARAM_NOT_EQUAL', counterfactual: { field, requested: value, allowed: constraint.equals } }
+
+    if( constraint.oneOf !== undefined && !constraint.oneOf.includes( value ) )
+      return { reasonCode: 'PARAM_NOT_IN_SET', counterfactual: { field, requested: value, allowed: [ ...constraint.oneOf ] } }
+  }
+
+  return null
+}
+
+/** A compact description of a constraint, for the missing-parameter case. */
+function describe( c: ParamConstraint ): unknown {
+  if( c.oneOf !== undefined )  return [ ...c.oneOf ]
+  if( 'equals' in c )          return c.equals
+  if( c.max !== undefined && c.min !== undefined ) return { min: c.min, max: c.max }
+  if( c.max !== undefined )    return { max: c.max }
+  if( c.min !== undefined )    return { min: c.min }
+  return null
+}

package/src/stem/tracts/biography.writer.ts

@@ -38,15 +38,15 @@ export class BiographyWriter {
     if( !fileLoggingEnabled() ) return
 
     const dataDir = process.env[ 'WILL_DATA_DIR' ] ?? './data'
-    const dir     = join( dataDir, 'wills', willId, 'profiles' )
+    const dir     = join( dataDir, 'wills', willId, 'profiles')
     try {
       if( !this._ensuredDirs.has( dir ) ){
         mkdirSync( dir, { recursive: true } )
         this._ensuredDirs.add( dir )
       }
-      appendFileSync( join( dir, file ), JSON.stringify( record ) + '\n', 'utf8' )
+      appendFileSync( join( dir, file ), JSON.stringify( record ) + '\n', 'utf8')
     } catch( err ){
-      logger.error( `[biography] ${file} write failed:`, err )
+      logger.error(`[biography] ${file} write failed:`, err )
     }
   }
   /**