@mindot/will 0.6.0 → 0.8.0

package/src/stem/mind.ts

@@ -25,6 +25,7 @@ import { validateWillIdentity }  from '#stem/guards/identity.guard'
 import { OutboxWriter } from '#stem/tracts/outbox.writer'
 import { ExecutiveSummarizer } from '#llm/summarizer'
 import type { LLMProvider } from '#llm/index'
+import { TableRouter, chainRouters, type ModelRouter, type RoutingRule } from '#llm/routing'
 import { resolveProfile } from '#profiles/index'
 import { DefaultVectorMemoryAdapter } from '#memory/vector.adapter'
 import { OpenAICompatibleEmbedder, MockEmbedder } from '#memory/vector.embedder'
@@ -46,6 +47,7 @@ import { effectorName, type EffectorDeclaration } from '#agency/types'
 
 import {
   TokenTracker,
+  type PriceTable,
   EnergyRegulator,
   SleepPressureRegulator,
   CircadianOscillator,
@@ -137,12 +139,54 @@ export interface WillModelConfig {
  * `apiKey` is held in memory only — it is never mirrored into state entities,
  * session logs, or the PMA.
  */
+export interface WillProviderConfig {
+  /** Credential for this provider. Held in memory only — never state/logs/PMA. */
+  apiKey?:  string
+  /** Base URL override — self-hosted or OpenAI-compatible endpoints. */
+  baseUrl?: string
+  /**
+   * USD per 1M tokens, keyed by model id. Host-owned on purpose: prices change
+   * on a vendor's schedule, differ per account, and are ~0 self-hosted, so they
+   * cannot be tracked from inside an npm release. These win over the engine's
+   * built-in fallback table.
+   *
+   * Cost is telemetry only — it never enters simulation state — so changing a
+   * price can never change what a mind does or break a replay.
+   */
+  prices?:  PriceTable
+}
+
 export interface WillLLMConfig {
   provider?:        LLMProvider
   apiKey?:          string
   baseUrl?:         string
   maxOutputTokens?: number
   timeoutMs?:       number
+  /**
+   * Everything the host knows about each provider — credential, endpoint, and
+   * prices — declared once per provider. The single-provider fields above stay
+   * the simple path; this map is for hosts reaching more than one.
+   */
+  providers?:       Partial<Record<LLMProvider, WillProviderConfig>>
+  /**
+   * Per-call model selection. Omitted (or NULL_ROUTER) means every call uses
+   * `model` above, exactly as before the seam existed.
+   *
+   * The router sees only the call's attribution — what kind of work it is and
+   * how much the moment demands — never who is paying or what anything costs.
+   * Routes name providers from the `providers` map above; a route to a provider
+   * with no credential falls back to the default rather than failing the call.
+   */
+  router?:          ModelRouter | null
+  /**
+   * Concrete LLM model id(s) for this Will — a single id for every role, or a
+   * per-role map. An explicit WILL_LLM_MODEL env pins the thinking roles
+   * (operator single-model deployments); unset roles fall back to `executive`,
+   * then the LLMDirector's built-in default. Product-level labels (pricing
+   * tiers, model families) live host-side and resolve to concrete ids BEFORE
+   * reaching the engine.
+   */
+  model?: string | WillModelConfig
 }
 
 /** Executive-side resolved roles (embedding is threaded separately). */
@@ -159,6 +203,91 @@ export interface ExecutiveModelRoles {
  * single-model deployment, full stop. Embedding is untouched by the pin
  * (different model family; the embedding stack has its own env).
  */
+/**
+ * Flatten the per-provider `prices` maps into one model→price table.
+ *
+ * Providers declare their own models, so collisions are not expected; if two
+ * do claim the same id, the first declared wins rather than silently taking
+ * whichever iterated last.
+ */
+export function mergeProviderPrices(
+  providers?: Partial<Record<LLMProvider, WillProviderConfig>>,
+): PriceTable | undefined {
+  if( !providers ) return undefined
+  const out: PriceTable = {}
+  for( const entry of Object.values( providers ) ){
+    for( const [ model, price ] of Object.entries( entry?.prices ?? {} ) ){
+      if( !( model in out ) ) out[ model ] = price
+    }
+  }
+  return Object.keys( out ).length > 0 ? out : undefined
+}
+
+/**
+ * Narrow the per-provider map to just what the LLM transport needs — the
+ * prices ride to the TokenTracker instead, so a credential map never carries
+ * pricing into the call path.
+ */
+export function providerCredentials(
+  providers: Partial<Record<LLMProvider, WillProviderConfig>>,
+): Partial<Record<LLMProvider, { apiKey: string; baseUrl?: string }>> {
+  const out: Partial<Record<LLMProvider, { apiKey: string; baseUrl?: string }>> = {}
+  for( const [ name, entry ] of Object.entries( providers ) ){
+    if( !entry?.apiKey ) continue   // no key ⇒ unusable; the router falls back
+    out[ name as LLMProvider ] = {
+      apiKey: entry.apiKey,
+      ...( entry.baseUrl ? { baseUrl: entry.baseUrl } : {} ),
+    }
+  }
+  return out
+}
+
+/**
+ * Compile the per-role model map into routing rules — MODEL_ROUTING W7.
+ *
+ * The role map and the router were two mechanisms answering one question
+ * ("which model serves this call?"). The map was implemented by giving each
+ * role its own cached `LLMDirector`, which meant role selection happened at
+ * *facet-spawn* time while routing happened at *call* time — two answers, one
+ * question, and a facet could be pinned to a model its work had since stopped
+ * matching. The map is now sugar: it desugars to rules and there is one
+ * mechanism left.
+ *
+ * The mapping is exact, because every role's call sites already tag themselves
+ * with the matching axis:
+ *
+ * | role           | rule                        | call sites                          |
+ * | :---           | :---                        | :---                                |
+ * | `summarizer`   | `category: 'summarizer'`    | the rolling summariser              |
+ * | `deliberation` | `function: 'deliberation'`  | the deliberation facet + its propose pass |
+ * | `conversation` | `function: 'conversation'` and `'outreach'` | the audition facets   |
+ * | `executive`    | — it *is* the default       | master, and every unlabelled facet  |
+ *
+ * Roles equal to `executive` emit no rule: a Will on a single model keeps an
+ * empty chain and stays byte-identical to one built before this seam existed.
+ *
+ * Routes carry no provider — a role has never had one. They inherit the Will's
+ * default provider, which is exactly what the per-role directors did.
+ */
+export function compileRoleRouter( roles: ExecutiveModelRoles ): ModelRouter | null {
+  const { executive, summarizer, deliberation, conversation } = roles
+  const distinct = ( model: string | null ): model is string => !!model && model !== executive
+
+  const rules: RoutingRule[] = []
+  if( distinct( summarizer ) )
+    rules.push( { category: 'summarizer', route: { model: summarizer } } )
+  if( distinct( deliberation ) )
+    rules.push( { function: 'deliberation', route: { model: deliberation } } )
+  if( distinct( conversation ) ){
+    // Outreach is the same voice speaking first — it has always shared the
+    // conversation model, and splitting it is the host's call, via a router.
+    rules.push( { function: 'conversation', route: { model: conversation } } )
+    rules.push( { function: 'outreach',     route: { model: conversation } } )
+  }
+
+  return rules.length > 0 ? new TableRouter( rules, 'role-map') : null
+}
+
 export function resolveModelRoles( model?: string | WillModelConfig ): ExecutiveModelRoles & { embedding: string | null } {
   const map = typeof model === 'string' ? { executive: model } : ( model ?? {} )
   const pin = process.env.WILL_LLM_MODEL
@@ -223,16 +352,6 @@ export interface WillConfig {
   /** Anatomy — 'mind' (default) or the no-LLM 'reflex' shell. */
   anatomy?: Anatomy
 
-  /**
-   * Concrete LLM model id(s) for this Will — a single id for every role, or a
-   * per-role map. An explicit WILL_LLM_MODEL env pins the thinking roles
-   * (operator single-model deployments); unset roles fall back to `executive`,
-   * then the LLMDirector's built-in default. Product-level labels (pricing
-   * tiers, model families) live host-side and resolve to concrete ids BEFORE
-   * reaching the engine.
-   */
-  model?: string | WillModelConfig
-
   /**
    * Per-Will LLM transport overrides (provider, BYO apiKey, baseUrl, output
    * cap, timeout). Unset fields fall back to WILL_LLM_* envs. The apiKey never
@@ -359,17 +478,17 @@ export interface MindAssembly {
   outbox:               OutboxMessage[]
 }
 
-// ── Cadence defaults per tier ─────────────────────────────────
+// ── Named executive cadences ──────────────────────────────────
 
 /**
  * Named executive cadences — ticks between LLM calls. Lower = reasons more often
- * (more responsive, higher COGS). Customers pick via `config.executiveInterval`
- * (clamped to `minExecutiveInterval`). See monetization.md "Cost Per Will-Hour".
+ * (more responsive, more tokens per Will-hour). Callers pick via
+ * `config.executiveInterval` (clamped to `minExecutiveInterval`).
  */
 export const EXECUTIVE_CADENCE = {
-  responsive: 30,  // Sonnet — premium/Enterprise; opt in via executiveInterval
-  balanced:   60,  // Sonnet — Pro default
-  economy:    90,  // Haiku  — Starter default
+  responsive: 30,  // most attentive, highest spend — opt in via executiveInterval
+  balanced:   60,  // default
+  economy:    90,  // least attentive, lowest spend
 } as const
 
 
@@ -666,6 +785,10 @@ function _constructCognition(
   // (attachTokenTracker), so usage/cost never conflates across Wills and
   // parallel runs stay isolated.
   const tokenTracker = new TokenTracker({
+    // Host prices, flattened from the per-provider map. Cost is telemetry only
+    // (it never enters state), so this can differ run to run without touching
+    // determinism.
+    prices:                  mergeProviderPrices( config.llm?.providers ),
     emitCostEvents:          true,
     costWarningThresholdUsd: 0.02,
     willId,
@@ -708,7 +831,7 @@ function _constructCognition(
 
   // Per-Will, per-ROLE models (env WILL_LLM_MODEL pins all thinking roles —
   // operator single-model deployments). No tier vocabulary inside the engine.
-  const modelRoles = resolveModelRoles( config.model )
+  const modelRoles = resolveModelRoles( config.llm?.model )
 
   const { embedder, vectorMemory } = _resolveVectorMemory( willId, randomSeed, config.vectorMemoryAdapter, config.disableVectorMemory, tokenTracker, config.testMode, modelRoles.embedding ?? undefined )
   const episodicConsolidator = new EpisodicConsolidator( vectorMemory ? { vectorMemory, ...(embedder ? { embedder } : {}) } : {} )
@@ -746,13 +869,21 @@ function _constructCognition(
   const executiveEngine   = new ExecutiveEngine({ executiveInterval, cooldownTicks: 5 })
 
   executiveEngine.willId = willId
-  executiveEngine.llm    = config.llm ?? null
-  executiveEngine.models = {
-    executive:    modelRoles.executive,
-    summarizer:   modelRoles.summarizer,
-    deliberation: modelRoles.deliberation,
-    conversation: modelRoles.conversation,
-  }
+  // Narrow the host's per-provider map to credentials for the call path; the
+  // prices from that same map went to the TokenTracker above.
+  // W7 — the per-role model map compiles into routing rules and joins the
+  // host's own router in one chain, so the engine receives a single answer to
+  // "which model serves this call?" instead of two. The host's router leads:
+  // that is the precedence the two mechanisms already had.
+  const roleRouter = compileRoleRouter( modelRoles )
+  executiveEngine.llm    = config.llm
+    ? {
+        ...config.llm,
+        ...( config.llm.providers ? { credentials: providerCredentials( config.llm.providers ) } : {} ),
+        router: chainRouters( config.llm.router, roleRouter ),
+      }
+    : ( roleRouter ? { router: roleRouter } : null )
+  executiveEngine.modelId = modelRoles.executive
   if( config.testMode ) executiveEngine.setTestMode( true )
   executiveEngine.attachWorkingMemory( workingMemory )
   executiveEngine.attachGoalManager( goalManager )

package/src/stem/policy/arbiter.ts

@@ -0,0 +1,171 @@
+// ─────────────────────────────────────────────────────────────
+// 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'
+
+/**
+ * WHY this denial is final — the distinction that makes a refusal learnable
+ * rather than a wall to re-probe forever. Each value selects a different
+ * cognitive fate; they are not degrees of one severity.
+ *
+ *   • 'class'     — the ACTION ITSELF is never permitted. Suppress the
+ *                   affordance hard, erase any learned envelope, and let go of
+ *                   a commitment currently deliberating toward it.
+ *   • 'parameter' — the action is fine; THESE ARGUMENTS were not (bound
+ *                   exceeded, wrong target). Narrow the envelope the Will
+ *                   reaches for; the ability stays.
+ *   • 'context'   — the refusal was NOT ABOUT THE ACTION at all (tainted
+ *                   context, unavailable dependency). Touch nothing: no
+ *                   availability delta, no envelope, no competence.
+ *
+ * POLICY_REAFFERENCE P5 widened this from 'class' | 'instance' after the HELM
+ * joint RFC ("Denials That Teach") identified that an instance-scoped refusal
+ * splits in two, and that the two halves demand opposite responses. These are
+ * OUR names for the distinctions, deliberately not HELM's wire spellings — see
+ * the naming-boundary note in .TODO/POLICY_REAFFERENCE.md. A provider adapter
+ * translates; this interface stays vendor-neutral.
+ */
+export type DenialFinality = 'class' | 'parameter' | 'context'
+
+/**
+ * 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 'parameter' — see
+   *  `asFinality` for why that, and not 'context', is the safe default. */
+  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 ⇒ 'parameter' (see `asFinality`). */
+export function finalityOf( verdict: Verdict ): DenialFinality {
+  return asFinality( verdict.finality )
+}
+
+/**
+ * Normalize an UNTYPED finality — one read back off entity metadata, a verdict
+ * tape, or a host ack, where the type system cannot help.
+ *
+ * Every such read goes through here rather than comparing string literals at
+ * the call site: the enum is a moving target (it widened once for the HELM
+ * joint RFC and may again), and a hand-written `=== 'class'` scattered through
+ * cognition is a mis-route that still typechecks.
+ *
+ * THE DEFAULT IS 'parameter', AND NEVER 'context'. The intuitive reading — an
+ * unlabelled denial should do the LEAST, so default to the fate that touches
+ * nothing — is wrong, and dangerously so. 'context' means *the mind learns
+ * nothing from this denial*, so it re-probes the same wall forever: the exact
+ * failure this whole epoch exists to fix, silently re-enabled for any provider
+ * that doesn't tag its refusals. 'context' is a claim only a provider that
+ * actually knows can make — it must be ASSERTED, never defaulted to.
+ * 'parameter' narrows without deleting, which is the honest conservative
+ * reading and preserves pre-P5 behaviour for an untagged denial exactly.
+ *
+ * Legacy 'instance' (the pre-P5 spelling) normalizes to 'parameter' by the same
+ * fallback, so tapes and snapshots written before the split replay unchanged.
+ */
+export function asFinality( raw: unknown ): DenialFinality {
+  return raw === 'class' ? 'class' : raw === 'context' ? 'context' : 'parameter'
+}

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 'parameter',
+ * 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 ?? 'parameter',
+          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
+}