Use counterfactual utility plasticity

Counterfactual Utility Plasticity (CUP) updates source and coalition utility inside the adaptive posterior from attributable feedback. It evaluates predictions captured before the outcome and uses the resulting utility estimates in later selections. Supported positive utility can activate a source coalition; sufficiently negative utility can inhibit it. The configured forgetting factor decays support and utility as new evidence arrives.

CUP participants are posterior prediction mechanisms such as contextual_memory and learned_model.

When CUP fits

Enable CUP when all of these conditions are true:

the Domain makes repeated decisions with attributable measured outcomes;
the adaptive posterior is enabled;
at least two posterior sources can become usable for the same relation;
source value may be complementary, redundant, or harmful under some conditions;
rewards can be normalized into [0,1];
the application can preserve pre-outcome source predictions and bind feedback to the committed decision.

CUP can support ordinary contextual decisions, temporally projected context, sequential workflows, and other decision surfaces that use the same adaptive posterior. It becomes eligible only when the current decision has enough usable sources and accumulated support. Tasks with one permanent source provide no coalition to adjudicate. Tasks at a metric ceiling provide no performance headroom even when CUP continues to learn structure.

How CUP enters selection

current context
available posterior sources
source predictions sealed before outcome
CUP utility adjustment
policy selection
measured feedback
source and coalition utility update

CUP evaluates the source predictions captured at decision time. Preserve them before the label or reward becomes visible.

Add CUP to the Domain

Enable the ordinary posterior, then add learning.posterior.plasticity. Numeric settings below are example parameters.

{
  "learning": {
    "enabled": true,
    "posterior": {
      "enabled": true,
      "scope": "relation",
      "learning_rate": 2.0,
      "forgetting_factor": 0.985,
      "minimum_feedback": 3,
      "minimum_support": 2.0,
      "variance_floor": 0.0025,
      "complexity_penalty": 0.01,
      "information_gain_weight": 0.0,
      "plasticity": {
        "enabled": true,
        "forgetting_factor": 0.99,
        "maximum_order": 2,
        "minimum_support": 16,
        "birth_threshold": 0.0025,
        "inhibition_threshold": 0.0025,
        "confidence_z": 1.644854,
        "complexity_penalty": 0.001,
        "weight_temperature": 0.025,
        "maximum_structures": 128,
        "maximum_pending": 256,
        "maximum_active": 4,
        "quantization_bins": 5,
        "prior_strength": 1.0,
        "loss": "log"
      }
    }
  }
}

Use this as a starting configuration when the reward is probabilistic or classification-like and the Domain exposes the normal memory and learned-model posterior sources.

Choose the maximum order

Setting	Structures considered	Use it when
`maximum_order: 1`	Singleton source utility	You want a lower-data source-adjudication test.
`maximum_order: 2`	Singletons and source pairs	Pairwise complementarity or redundancy matters. This is the recommended general starting point.

For the example sources below, maximum_order: 2 permits singleton structures and their pair:

contextual_memory
learned_model
contextual_memory × learned_model

Increasing maximum_order expands the candidate space and evidence burden. Use a higher order only when the source count, sample budget, and evaluation design justify it.

Read the main controls

Field	Function
`minimum_support`	Delays structural activation until enough effective evidence exists.
`birth_threshold`	Requires positive irreducible utility before a structure becomes active.
`inhibition_threshold`	Requires negative utility before a structure becomes inhibitory.
`confidence_z`	Controls the confidence interval used for structural decisions.
`weight_temperature`	Controls how sharply supported utility becomes structural weight.
`forgetting_factor`	Decays stale support and utility under distribution shift.
`maximum_active`	Bounds the number of structures applied to one decision.
`loss`	Defines the prequential loss used to assign source utility.

Tune thresholds only after the integration trace shows a concrete support, churn, or responsiveness problem. Preserve the full configuration and ordered event record for every test.

Make a second source usable

An empty Domain usually begins with contextual_memory as the available posterior source. learned_model becomes usable only after training has enough admitted samples and its candidate model passes validation. The following example parameters enable training of a candidate learned-model source:

{
  "learning": {
    "context": {
      "feature_paths": ["values.observation"],
      "event_types": [],
      "max_samples": 4096
    },
    "training": {
      "enabled": true,
      "min_samples": 64,
      "retrain_interval": 128,
      "dimensions": 256,
      "epochs": 75,
      "learning_rate": 0.02
    }
  }
}

If learned_model never becomes usable, CUP has no valid multi-source test. Inspect the feedback-policy sample count, training status, validation report, model type, and posterior source list before tuning plasticity.

Bind reward to the sealed decision

CUP learns from the ordinary Domain query and feedback loop. Query first and preserve the posterior diagnostics before the outcome is visible. Then submit one measured feedback write for the executed policy.

{
  "session_id": "ignored",
  "outcome": "correct",
  "feedback_kind": "execution",
  "decision_id": "DECISION_FROM_QUERY",
  "relation": "selects_output",
  "policy": "emit_2",
  "context": {
    "values": {
      "observation": 2
    },
    "metadata": {
      "episode_id": "episode-0007",
      "step": 42
    }
  },
  "values": {
    "correct": 1.0
  }
}

The Domain reward declaration should resolve this outcome into [0,1]. Supply the real relation, executed policy, and a supported decision-time context source. A valid decision_id gives the strongest sealed attribution. Do not send a second feedback record for an unexecuted policy. Do not return a counterfactual label, future answer, source score, confidence value, or post-outcome model prediction as reward.

Inspect CUP in the response

For each candidate, inspect:

ranked_hypotheses[].contextual_policy.posterior_adjudication.sources
ranked_hypotheses[].contextual_policy.posterior_adjudication.counterfactual_utility_plasticity

The active service can expose whether CUP was eligible and applied, the source predictions used, the posterior mean before and after adjustment, and the structures applied to that candidate. Preserve the complete pre-feedback candidate objects. Keep these audit fields in the application trace:

{
  "posterior_sources": ["contextual_memory", "learned_model"],
  "cup_applied": true
}

When the active service returns structures, preserve their participants, order, status, support, utility interval, and applied weight:

[
  {
    "participants": ["learned_model"],
    "order": 1,
    "status": "consolidated",
    "effective_support": 24.0,
    "mean_utility": 0.03,
    "utility_interval": [0.01, 0.05],
    "weight": 0.6
  },
  {
    "participants": ["contextual_memory", "learned_model"],
    "order": 2,
    "status": "inhibited",
    "effective_support": 24.0,
    "mean_utility": -0.02,
    "utility_interval": [-0.04, -0.01],
    "weight": -0.4
  }
]

Singleton utility describes a source contribution. Pair utility measures the contribution beyond the individual members; its sign and support determine whether the pair consolidates or becomes inhibitory. The numeric values above illustrate the response shape. Use the values returned by the active service when auditing a real decision.

Verify CUP in your integration

Use a short controlled stream before production use:

Start with fresh Domain and session state.
Confirm that contextual_memory appears in posterior source diagnostics.
Admit enough attributable outcomes for the configured model-training boundary.
Confirm that a validated learned_model becomes usable.
Preserve pre-feedback source predictions for each committed decision.
Continue feedback until effective support can reach minimum_support.
Inspect whether CUP was eligible, whether it was applied, and which structures affected the candidate.
Repeat selected queries with feedback disabled and confirm that learner-state fingerprints remain unchanged.

Failure checks

If cup_applied remains false, inspect these conditions in order:

learning.enabled is true;
learning.posterior.enabled is true;
learning.posterior.plasticity.enabled is true;
at least two sources appear in posterior diagnostics;
the trained model is installed and usable;
feedback supplies a normalized measured reward;
feedback is attributed to the executed relation and policy;
effective support has reached minimum_support;
source predictions were captured before the outcome;
the current condition has eligible candidate structures.

If metrics stay unchanged with CUP active, inspect source redundancy, task ceiling, support thresholds, structure churn, metric choice, and whether a simpler source-selection control is stronger.

Choose how a Domain learns

Match the Domain to immediate feedback, transition prediction, temporal context, or delayed credit.

Use TCP

Add bounded recent history before posterior source prediction and selection.

Learn from outcomes

Bind the measured consequence to the committed decision.

Verify adaptation

Use paired streams, frozen evaluation, and learner-state fingerprints.

Get started

Concepts

Guides

Discovery

Operations

API reference

When CUP fits

How CUP enters selection

Add CUP to the Domain

Choose the maximum order

Read the main controls

Make a second source usable

Bind reward to the sealed decision

Inspect CUP in the response

Verify CUP in your integration

Failure checks

Choose how a Domain learns

Use TCP

Learn from outcomes

Verify adaptation

​When CUP fits

​How CUP enters selection

​Add CUP to the Domain

​Choose the maximum order

​Read the main controls

​Make a second source usable

​Bind reward to the sealed decision

​Inspect CUP in the response

​Verify CUP in your integration

​Failure checks

Choose how a Domain learns

Use TCP

Learn from outcomes

Verify adaptation

When CUP fits

How CUP enters selection

Add CUP to the Domain

Choose the maximum order

Read the main controls

Make a second source usable

Bind reward to the sealed decision

Inspect CUP in the response

Verify CUP in your integration

Failure checks