Use counterfactual utility plasticity

Configure source and coalition utility learning from attributable online feedback.

Use this when an adaptive posterior has multiple usable prediction sources. CUP learns which sources and coalitions contribute predictive utility.

Counterfactual Utility Plasticity (CUP) is an online structural rule inside the adaptive posterior. It learns which available prediction sources, and which small coalitions of sources, add predictive utility before an outcome is observed.

Useful source coalitions become active posterior structures. Harmful coalitions become inhibitory structures. Their support and utility decay as the stream changes. CUP does not train a separate policy model.

CUP participants are posterior prediction mechanisms such as contextual_memory and learned_model. Domain context features do not automatically become CUP participants.

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

1. current context
2. available posterior sources
3. source predictions sealed before outcome
4. CUP utility adjustment
5. policy selection
6. measured feedback
7. source and coalition utility update

The pre-outcome requirement matters. CUP evaluates the predictions that existed when the decision was made. It must never construct utility from a source score calculated after the label or reward becomes visible.

Add CUP to the Domain

Enable the ordinary posterior, then add learning.posterior.plasticity.

{
  "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.

With two usable sources, order 2 can represent at most three coalitions:

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.

Use a training configuration that can make a validated learned-model source available:

{
  "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.

At minimum, keep these two 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
  }
]

The singleton structure represents source utility. The pair represents irreducible utility beyond its members. A positive structure can consolidate, while a sufficiently negative structure can become 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:

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

This check validates source availability, attribution, support, and structural application. Application-level evaluation should remain separate from the usage guide.

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 CUP applies but metrics do not improve, 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.