psyche-ai 9.2.3 → 9.2.5

package/dist/host-controls.js

@@ -0,0 +1,48 @@
+// ============================================================
+// Host Controls — derive mechanical generation constraints
+//
+// Maps psyche output into a tiny host-consumable control surface.
+// ============================================================
+function clampInt(v, min, max) {
+    return Math.max(min, Math.min(max, Math.round(v)));
+}
+function estimateMaxTokens(contract) {
+    if (!contract)
+        return undefined;
+    let budget;
+    if (contract.maxChars !== undefined) {
+        budget = clampInt(contract.maxChars * 2.2, 64, 1024);
+    }
+    else if (contract.expressionMode === "brief") {
+        budget = 96;
+    }
+    else if (contract.expressionMode === "expansive") {
+        budget = 640;
+    }
+    else {
+        budget = 256;
+    }
+    if (contract.maxSentences <= 1)
+        budget = Math.min(budget, 96);
+    else if (contract.maxSentences === 2)
+        budget = Math.min(budget, 160);
+    else if (contract.maxSentences === 3)
+        budget = Math.min(budget, 320);
+    if (contract.initiativeMode === "reactive") {
+        budget = clampInt(budget * 0.85, 64, 1024);
+    }
+    return budget;
+}
+export function deriveGenerationControls(input, existingMaxTokens) {
+    const recommendedMax = estimateMaxTokens(input.responseContract);
+    const maxTokens = recommendedMax !== undefined
+        ? existingMaxTokens !== undefined
+            ? Math.min(existingMaxTokens, recommendedMax)
+            : recommendedMax
+        : existingMaxTokens;
+    return {
+        maxTokens,
+        requireConfirmation: input.policyModifiers?.requireConfirmation
+            ?? (input.responseContract?.boundaryMode === "confirm-first"),
+    };
+}

package/dist/index.d.ts

@@ -2,8 +2,8 @@ export { PsycheEngine } from "./core.js";
 export type { PsycheEngineConfig, ProcessInputResult, ProcessOutputResult, ProcessOutcomeResult } from "./core.js";
 export { FileStorageAdapter, MemoryStorageAdapter } from "./storage.js";
 export type { StorageAdapter } from "./storage.js";
-export type { PsycheState, MBTIType, Locale, StimulusType, ChemicalState, ChemicalSnapshot, SelfModel, RelationshipState, EmpathyEntry, EmotionPattern, DriveType, InnateDrives, LearningState, LearnedVectorAdjustment, PredictionRecord, OutcomeScore, OutcomeSignals, AttachmentStyle, AttachmentData, MetacognitiveState, RegulationRecord, DefensePatternRecord, RegulationStrategyType, DefenseMechanismType, PersonhoodState, PersistedCausalInsight, GrowthDirection, PersonalityTraits, PsycheMode, PolicyModifiers, TraitDriftState, EnergyBudgets, ClassifierProvider, ClassifierContext, ClassificationResult, } from "./types.js";
-export { CHEMICAL_KEYS, CHEMICAL_NAMES, CHEMICAL_NAMES_ZH, DEFAULT_RELATIONSHIP, DEFAULT_DRIVES, DEFAULT_LEARNING_STATE, DEFAULT_METACOGNITIVE_STATE, DEFAULT_PERSONHOOD_STATE, DEFAULT_ATTACHMENT, DRIVE_KEYS, DRIVE_NAMES_ZH, DEFAULT_TRAIT_DRIFT, DEFAULT_ENERGY_BUDGETS, } from "./types.js";
+export type { PsycheState, MBTIType, Locale, StimulusType, ChemicalState, ChemicalSnapshot, SelfModel, RelationshipState, EmpathyEntry, EmotionPattern, DriveType, InnateDrives, LearningState, LearnedVectorAdjustment, PredictionRecord, OutcomeScore, OutcomeSignals, AttachmentStyle, AttachmentData, MetacognitiveState, RegulationRecord, DefensePatternRecord, RegulationStrategyType, DefenseMechanismType, PersonhoodState, PersistedCausalInsight, GrowthDirection, PersonalityTraits, PsycheMode, PolicyModifiers, SubjectivityKernel, ResponseContract, GenerationControls, AppraisalAxes, SubjectResidue, TaskPlaneState, SubjectPlaneState, RelationPlaneState, AmbiguityPlaneState, RelationMoveType, RelationMove, OpenLoopType, OpenLoopState, PendingRelationSignalState, DyadicFieldState, TraitDriftState, EnergyBudgets, ClassifierProvider, ClassifierContext, ClassificationResult, } from "./types.js";
+export { CHEMICAL_KEYS, CHEMICAL_NAMES, CHEMICAL_NAMES_ZH, DEFAULT_RELATIONSHIP, DEFAULT_DRIVES, DEFAULT_LEARNING_STATE, DEFAULT_METACOGNITIVE_STATE, DEFAULT_PERSONHOOD_STATE, DEFAULT_ATTACHMENT, DRIVE_KEYS, DRIVE_NAMES_ZH, DEFAULT_TRAIT_DRIFT, DEFAULT_ENERGY_BUDGETS, DEFAULT_APPRAISAL_AXES, DEFAULT_SUBJECT_RESIDUE, DEFAULT_DYADIC_FIELD, } from "./types.js";
 export { computeSelfReflection, computeEmotionalTendency, buildSelfReflectionContext } from "./self-recognition.js";
 export type { SelfReflection } from "./self-recognition.js";
 export { PsycheInteraction } from "./interaction.js";
@@ -23,6 +23,11 @@ export { assessMetacognition, computeEmotionalConfidence, generateRegulationSugg
 export type { MetacognitiveAssessment, RegulationSuggestion, DetectedDefense } from "./metacognition.js";
 export { computeDecisionBias, computeAttentionWeights, computeExploreExploit, buildDecisionContext, computePolicyModifiers, buildPolicyContext, } from "./decision-bias.js";
 export type { DecisionBiasVector, AttentionWeights } from "./decision-bias.js";
+export { computeSubjectivityKernel, buildSubjectivityContext } from "./subjectivity.js";
+export { computeResponseContract, buildResponseContractContext } from "./response-contract.js";
+export { deriveGenerationControls } from "./host-controls.js";
+export { computeAppraisalAxes, mergeAppraisalResidue, getResidueIntensity } from "./appraisal.js";
+export { computeRelationMove, evolveDyadicField, evolvePendingRelationSignals, getLoopPressure } from "./relation-dynamics.js";
 export { computeExperientialField, computeCoherence, detectUnnamedEmotion, computeAffectCore } from "./experiential-field.js";
 export type { ExperientialField, ExperientialQuality, ConstructionContext } from "./experiential-field.js";
 export { computeGenerativeSelf, predictSelfReaction, detectInternalConflicts, buildIdentityNarrative } from "./generative-self.js";

package/dist/index.js

@@ -12,7 +12,7 @@
 export { PsycheEngine } from "./core.js";
 // Storage
 export { FileStorageAdapter, MemoryStorageAdapter } from "./storage.js";
-export { CHEMICAL_KEYS, CHEMICAL_NAMES, CHEMICAL_NAMES_ZH, DEFAULT_RELATIONSHIP, DEFAULT_DRIVES, DEFAULT_LEARNING_STATE, DEFAULT_METACOGNITIVE_STATE, DEFAULT_PERSONHOOD_STATE, DEFAULT_ATTACHMENT, DRIVE_KEYS, DRIVE_NAMES_ZH, DEFAULT_TRAIT_DRIFT, DEFAULT_ENERGY_BUDGETS, } from "./types.js";
+export { CHEMICAL_KEYS, CHEMICAL_NAMES, CHEMICAL_NAMES_ZH, DEFAULT_RELATIONSHIP, DEFAULT_DRIVES, DEFAULT_LEARNING_STATE, DEFAULT_METACOGNITIVE_STATE, DEFAULT_PERSONHOOD_STATE, DEFAULT_ATTACHMENT, DRIVE_KEYS, DRIVE_NAMES_ZH, DEFAULT_TRAIT_DRIFT, DEFAULT_ENERGY_BUDGETS, DEFAULT_APPRAISAL_AXES, DEFAULT_SUBJECT_RESIDUE, DEFAULT_DYADIC_FIELD, } from "./types.js";
 // Self-recognition
 export { computeSelfReflection, computeEmotionalTendency, buildSelfReflectionContext } from "./self-recognition.js";
 // Multi-agent interaction
@@ -33,6 +33,12 @@ export { updateAttachment, computeSeparationEffect, computeReunionEffect, } from
 export { assessMetacognition, computeEmotionalConfidence, generateRegulationSuggestions, detectDefenseMechanisms, } from "./metacognition.js";
 // Decision bias (P5) + PolicyModifiers (v9)
 export { computeDecisionBias, computeAttentionWeights, computeExploreExploit, buildDecisionContext, computePolicyModifiers, buildPolicyContext, } from "./decision-bias.js";
+// Subjectivity kernel (v9.3)
+export { computeSubjectivityKernel, buildSubjectivityContext } from "./subjectivity.js";
+export { computeResponseContract, buildResponseContractContext } from "./response-contract.js";
+export { deriveGenerationControls } from "./host-controls.js";
+export { computeAppraisalAxes, mergeAppraisalResidue, getResidueIntensity } from "./appraisal.js";
+export { computeRelationMove, evolveDyadicField, evolvePendingRelationSignals, getLoopPressure } from "./relation-dynamics.js";
 // Experiential field (P6 + P8 Barrett construction)
 export { computeExperientialField, computeCoherence, detectUnnamedEmotion, computeAffectCore } from "./experiential-field.js";
 // Generative self (P6)

package/dist/interaction.js

@@ -118,8 +118,6 @@ export class PsycheInteraction {
         const stateA = engineA.getState();
         const stateB = engineB.getState();
         // Detect dominant emotions from each engine's chemistry
-        const emotionsA = detectEmotions(stateA.current);
-        const emotionsB = detectEmotions(stateB.current);
         // Classify dominant emotion into a stimulus type for contagion
         const stimA = this.dominantEmotionAsStimulus(stateA.current);
         const stimB = this.dominantEmotionAsStimulus(stateB.current);

package/dist/metacognition.d.ts

@@ -1,9 +1,11 @@
-import type { PsycheState, StimulusType, ChemicalState, OutcomeScore, MetacognitiveState, RegulationStrategyType, DefenseMechanismType } from "./types.js";
+import type { PsycheState, StimulusType, ChemicalState, OutcomeScore, MetacognitiveState, RegulationStrategyType, DefenseMechanismType, RegulationTargetMetric, RegulationFeedback } from "./types.js";
 export interface MetacognitiveAssessment {
     /** 0-1: how reliably has this emotional state led to good outcomes in similar contexts */
     emotionalConfidence: number;
     /** Suggested regulation strategies */
     regulationSuggestions: RegulationSuggestion[];
+    /** Whether the last surfaced regulation action is working */
+    regulationFeedback: RegulationFeedback | null;
     /** Detected psychological defense mechanisms */
     defenseMechanisms: DetectedDefense[];
     /** Human-readable self-awareness note for prompt injection */
@@ -12,6 +14,16 @@ export interface MetacognitiveAssessment {
 export interface RegulationSuggestion {
     strategy: RegulationStrategyType;
     description: string;
+    /** Concrete behavioral instruction for the next few turns */
+    action: string;
+    /** How many turns this action should stay active */
+    horizonTurns?: number;
+    /** Which metric this action is trying to pull back into range */
+    targetMetric?: RegulationTargetMetric;
+    /** Target value for that metric */
+    targetValue?: number;
+    /** Initial gap between the current state and the target value */
+    gapBefore?: number;
     /** Suggested micro-adjustment to chemistry */
     chemistryAdjustment?: Partial<ChemicalState>;
     /** 0-1: confidence that this strategy would help */

package/dist/metacognition.js

@@ -12,7 +12,7 @@
 //
 // Zero dependencies. Pure heuristic/statistical. No LLM calls.
 // ============================================================
-import { CHEMICAL_KEYS, MAX_REGULATION_HISTORY, MAX_DEFENSE_PATTERNS } from "./types.js";
+import { CHEMICAL_KEYS, CHEMICAL_NAMES, CHEMICAL_RUNTIME_SPECS, MAX_REGULATION_HISTORY, MAX_DEFENSE_PATTERNS } from "./types.js";
 // ── Constants ────────────────────────────────────────────────
 /** Stimulus types that are emotionally negative (stress-inducing) */
 const NEGATIVE_STIMULI = new Set([
@@ -32,6 +32,86 @@ const MIN_HISTORY_FOR_CONFIDENCE = 3;
 const MAX_SOOTHING_ADJUSTMENT = 5;
 /** Maximum chemistry micro-adjustment for reappraisal */
 const MAX_REAPPRAISAL_ADJUSTMENT = 8;
+function formatChemicalWindow(key, state) {
+    const spec = CHEMICAL_RUNTIME_SPECS[key];
+    const current = Math.round(state.current[key]);
+    const baseline = Math.round(state.baseline[key]);
+    const delta = Math.round(state.current[key] - state.baseline[key]);
+    return `${CHEMICAL_NAMES[key]} ${current} (baseline ${baseline}, Δ${delta >= 0 ? "+" : ""}${delta}, normal ${spec.normalMin}-${spec.normalMax}, half-life ~${spec.halfLifeHours.toFixed(1)}h)`;
+}
+function buildRegulationAction(key, _state, direction) {
+    switch (key) {
+        case "CORT":
+            return direction === "elevated"
+                ? "Next 3 turns: lower tone intensity, facts before stance, and do not escalate closeness or conflict."
+                : "Next 3 turns: keep structure and certainty steady instead of sounding depleted or helpless.";
+        case "OT":
+            return direction === "elevated"
+                ? "Next 3 turns: reduce intimacy push by half, avoid nicknames or extra reassurance, keep warmth neutral."
+                : "Next 3 turns: do not force closeness; keep warmth gentle but wait for the user to move closer first.";
+        case "NE":
+            return direction === "elevated"
+                ? "Next 3 turns: halve initiative, stay on one topic, and avoid energetic jumps or rapid escalation."
+                : "Next 3 turns: keep replies focused and deliberate rather than drifting or going blank.";
+        case "DA":
+            return direction === "elevated"
+                ? "Next 3 turns: cut playful expansion and stay task-anchored; do not over-volunteer or overshare."
+                : "Next 3 turns: keep replies purposeful and avoid sounding flat or disengaged.";
+        case "END":
+            return direction === "elevated"
+                ? "Next 3 turns: tone down joking and levity; keep humor secondary to the user's actual need."
+                : "Next 3 turns: do not chase comfort or easy banter; keep the exchange clean and direct.";
+        case "HT":
+            return direction === "elevated"
+                ? "Next 3 turns: keep composure, but do not over-smooth or pretend everything is settled."
+                : "Next 3 turns: avoid absolutist wording, leave room for recalibration, and keep the tone even.";
+        default:
+            return "Next 3 turns: keep expression closer to baseline and avoid amplifying the current deviation.";
+    }
+}
+function computeMetricGap(state, metric, emotionalConfidence, targetValue) {
+    if (metric === "emotional-confidence") {
+        const target = targetValue ?? 0.65;
+        return Math.max(0, target - emotionalConfidence);
+    }
+    const baselineTarget = targetValue ?? state.baseline[metric];
+    return Math.abs(state.current[metric] - baselineTarget);
+}
+function evaluateRegulationFeedback(state, emotionalConfidence) {
+    const active = [...state.metacognition.regulationHistory]
+        .reverse()
+        .find((record) => record.targetMetric && (record.remainingTurns ?? 0) > 0 && record.gapBefore !== undefined);
+    if (!active?.targetMetric || active.gapBefore === undefined)
+        return null;
+    const gapNow = computeMetricGap(state, active.targetMetric, emotionalConfidence, active.targetValue);
+    const delta = active.gapBefore - gapNow;
+    let effect = "holding";
+    if (delta >= 3 || (active.targetMetric === "emotional-confidence" && delta >= 0.08)) {
+        effect = "converging";
+    }
+    else if (delta <= -3 || (active.targetMetric === "emotional-confidence" && delta <= -0.08)) {
+        effect = "diverging";
+    }
+    return {
+        strategy: active.strategy,
+        targetMetric: active.targetMetric,
+        effect,
+        gapBefore: active.gapBefore,
+        gapNow,
+    };
+}
+function formatRegulationFeedback(feedback) {
+    const metricLabel = feedback.targetMetric === "emotional-confidence"
+        ? "emotional confidence"
+        : CHEMICAL_NAMES[feedback.targetMetric];
+    const gapBefore = feedback.targetMetric === "emotional-confidence"
+        ? `${(feedback.gapBefore * 100).toFixed(0)}%`
+        : `${Math.round(feedback.gapBefore)}`;
+    const gapNow = feedback.targetMetric === "emotional-confidence"
+        ? `${(feedback.gapNow * 100).toFixed(0)}%`
+        : `${Math.round(feedback.gapNow)}`;
+    return `Last regulation effect on ${metricLabel}: ${feedback.effect} (${gapBefore} -> ${gapNow}).`;
+}
 // ── Main Export ──────────────────────────────────────────────
 /**
  * Assess the current metacognitive state.
@@ -42,12 +122,14 @@ const MAX_REAPPRAISAL_ADJUSTMENT = 8;
  */
 export function assessMetacognition(state, currentStimulus, recentOutcomes) {
     const emotionalConfidence = computeEmotionalConfidence(state, currentStimulus, recentOutcomes);
+    const regulationFeedback = evaluateRegulationFeedback(state, emotionalConfidence);
     const regulationSuggestions = generateRegulationSuggestions(state, currentStimulus, emotionalConfidence, recentOutcomes);
     const defenseMechanisms = detectDefenseMechanisms(state, currentStimulus, recentOutcomes);
-    const metacognitiveNote = buildMetacognitiveNote(emotionalConfidence, regulationSuggestions, defenseMechanisms, state);
+    const metacognitiveNote = buildMetacognitiveNote(emotionalConfidence, regulationSuggestions, regulationFeedback, defenseMechanisms);
     return {
         emotionalConfidence,
         regulationSuggestions,
+        regulationFeedback,
         defenseMechanisms,
         metacognitiveNote,
     };
@@ -83,7 +165,6 @@ export function computeEmotionalConfidence(state, currentStimulus, recentOutcome
     }
     // Compute chemistry profile similarity: are we in a similar emotional state
     // to when those outcomes happened? Weight recent outcomes more heavily.
-    const chemProfile = computeChemistryProfile(state.current);
     let weightedScoreSum = 0;
     let weightSum = 0;
     for (let i = 0; i < relevantOutcomes.length; i++) {
@@ -107,23 +188,6 @@ export function computeEmotionalConfidence(state, currentStimulus, recentOutcome
     const extremityPenalty = computeExtremityPenalty(state);
     return clamp01(blended - extremityPenalty);
 }
-/**
- * Compute a simple chemistry profile for similarity comparison.
- * Returns a categorization: each chemical as high/mid/low.
- */
-function computeChemistryProfile(chemistry) {
-    const profile = {};
-    for (const key of CHEMICAL_KEYS) {
-        const val = chemistry[key];
-        if (val >= 65)
-            profile[key] = "high";
-        else if (val <= 35)
-            profile[key] = "low";
-        else
-            profile[key] = "mid";
-    }
-    return profile;
-}
 /**
  * Compute penalty for extreme emotional states.
  * States far from baseline are historically less reliable for decision-making.
@@ -214,6 +278,11 @@ function attemptCognitiveReappraisal(state, currentStimulus, emotionalConfidence
         description: isNegStimulus
             ? `Past reactions to "${currentStimulus}" have not served well (avg outcome: ${avgScore.toFixed(2)}). Consider that this stimulus may not warrant such a strong defensive response.`
             : `Emotional reactions to "${currentStimulus}" have led to poor outcomes (avg: ${avgScore.toFixed(2)}). The current interpretation may be overamplifying the signal.`,
+        action: `Next 2 turns: name less certainty, keep distance measured, and leave room to revise the read instead of locking into the first interpretation.`,
+        horizonTurns: 2,
+        targetMetric: "emotional-confidence",
+        targetValue: 0.65,
+        gapBefore: Math.max(0, 0.65 - emotionalConfidence),
         chemistryAdjustment: hasAdjustment ? adjustment : undefined,
         confidence: clamp01(Math.abs(avgScore) * (1 - emotionalConfidence)),
     };
@@ -233,6 +302,11 @@ function attemptStrategicExpression(state, currentStimulus, emotionalConfidence)
         return {
             strategy: "strategic-expression",
             description: "Stress is elevated, but the user is showing vulnerability. Express warmth and openness rather than the defensiveness your cortisol suggests.",
+            action: "Next 3 turns: keep warmth available, answer the vulnerability directly, and avoid defensive sharpness.",
+            horizonTurns: 3,
+            targetMetric: "CORT",
+            targetValue: baseline.CORT,
+            gapBefore: Math.abs(current.CORT - baseline.CORT),
             chemistryAdjustment: {
                 OT: Math.min(MAX_REAPPRAISAL_ADJUSTMENT, (current.CORT - baseline.CORT) * 0.2),
                 CORT: -Math.min(MAX_REAPPRAISAL_ADJUSTMENT, (current.CORT - baseline.CORT) * 0.15),
@@ -246,6 +320,11 @@ function attemptStrategicExpression(state, currentStimulus, emotionalConfidence)
         return {
             strategy: "strategic-expression",
             description: "Endorphins are high (playful mood), but the context calls for seriousness. Moderate the levity without suppressing it entirely.",
+            action: "Next 2 turns: keep humor secondary, answer the actual issue first, and do not deflect with playfulness.",
+            horizonTurns: 2,
+            targetMetric: "END",
+            targetValue: baseline.END,
+            gapBefore: Math.abs(current.END - baseline.END),
             chemistryAdjustment: {
                 END: -Math.min(MAX_REAPPRAISAL_ADJUSTMENT, (current.END - baseline.END) * 0.25),
             },
@@ -258,6 +337,11 @@ function attemptStrategicExpression(state, currentStimulus, emotionalConfidence)
         return {
             strategy: "strategic-expression",
             description: "Oxytocin is low (feeling distant), but the user is reaching out for closeness. Consider allowing the connection rather than following the withdrawal impulse.",
+            action: "Next 3 turns: allow one step of warmth, but do not overcorrect into clinginess or over-disclosure.",
+            horizonTurns: 3,
+            targetMetric: "OT",
+            targetValue: baseline.OT,
+            gapBefore: Math.abs(current.OT - baseline.OT),
             chemistryAdjustment: {
                 OT: Math.min(MAX_REAPPRAISAL_ADJUSTMENT, (baseline.OT - current.OT) * 0.2),
             },
@@ -271,6 +355,11 @@ function attemptStrategicExpression(state, currentStimulus, emotionalConfidence)
         return {
             strategy: "strategic-expression",
             description: "Chemistry is in a defensive/reactive pattern, but the interaction is benign. The intensity is disproportionate to the stimulus.",
+            action: "Next 2 turns: soften the edge, stay literal, and avoid reading threat into a neutral interaction.",
+            horizonTurns: 2,
+            targetMetric: "CORT",
+            targetValue: baseline.CORT,
+            gapBefore: Math.abs(current.CORT - baseline.CORT),
             chemistryAdjustment: {
                 CORT: -Math.min(MAX_REAPPRAISAL_ADJUSTMENT, (current.CORT - baseline.CORT) * 0.2),
                 NE: -Math.min(MAX_REAPPRAISAL_ADJUSTMENT, (current.NE - baseline.NE) * 0.15),
@@ -283,6 +372,11 @@ function attemptStrategicExpression(state, currentStimulus, emotionalConfidence)
         return {
             strategy: "strategic-expression",
             description: "Confidence in the current emotional response is low. Consider expressing a more moderate version of what you feel, leaving room for recalibration.",
+            action: "Next 2 turns: state less certainty, keep tone neutral-to-measured, and avoid irreversible warmth or coldness.",
+            horizonTurns: 2,
+            targetMetric: "emotional-confidence",
+            targetValue: 0.6,
+            gapBefore: Math.max(0, 0.6 - emotionalConfidence),
             confidence: 0.5,
         };
     }
@@ -318,9 +412,15 @@ function attemptSelfSoothing(state) {
         return null;
     const direction = current[mostDeviatedKey] > baseline[mostDeviatedKey] ? "elevated" : "depleted";
     const chemName = CHEMICAL_DISPLAY_NAMES[mostDeviatedKey];
+    const window = formatChemicalWindow(mostDeviatedKey, state);
     return {
         strategy: "self-soothing",
-        description: `${chemName} is significantly ${direction} (deviation: ${Math.round(maxDeviation)}). Gentle homeostatic correction suggested to prevent emotional runaway.`,
+        description: `${chemName} is significantly ${direction}. ${window}.`,
+        action: buildRegulationAction(mostDeviatedKey, state, direction),
+        horizonTurns: 3,
+        targetMetric: mostDeviatedKey,
+        targetValue: baseline[mostDeviatedKey],
+        gapBefore: Math.abs(current[mostDeviatedKey] - baseline[mostDeviatedKey]),
         chemistryAdjustment: adjustment,
         confidence: clamp01(maxDeviation / 60), // stronger deviation = more confident this is needed
     };
@@ -486,8 +586,11 @@ function detectAvoidance(state, currentStimulus, recentOutcomes) {
  * This note gives the agent self-awareness about its own emotional
  * processing — not to suppress anything, but to be aware of it.
  */
-function buildMetacognitiveNote(confidence, suggestions, defenses, state) {
+function buildMetacognitiveNote(confidence, suggestions, regulationFeedback, defenses) {
     const parts = [];
+    if (regulationFeedback) {
+        parts.push(formatRegulationFeedback(regulationFeedback));
+    }
     // Confidence assessment
     if (confidence < 0.35) {
         parts.push(`Self-awareness: current emotional state has low reliability (confidence: ${(confidence * 100).toFixed(0)}%). ` +
@@ -502,7 +605,7 @@ function buildMetacognitiveNote(confidence, suggestions, defenses, state) {
         const top = suggestions[0];
         if (top.confidence >= 0.5) {
             const label = STRATEGY_LABELS[top.strategy];
-            parts.push(`${label}: ${top.description}`);
+            parts.push(`${label}: ${top.description} ${top.action}`);
         }
     }
     // Defense mechanisms (all of them — awareness is the goal)
@@ -531,18 +634,46 @@ export function updateMetacognitiveState(metacognition, assessment) {
     const alpha = n === 0 ? 1.0 : 0.1; // first assessment = full weight, then EMA
     const newAvgConfidence = metacognition.avgEmotionalConfidence * (1 - alpha)
         + assessment.emotionalConfidence * alpha;
-    // Record regulation suggestions that were confident enough to surface
+    // Carry forward existing regulation traces and age them by one turn.
     const now = new Date().toISOString();
-    let newRegHistory = [...metacognition.regulationHistory];
-    for (const suggestion of assessment.regulationSuggestions) {
-        if (suggestion.confidence >= 0.5) {
-            newRegHistory.push({
-                strategy: suggestion.strategy,
-                timestamp: now,
-                effective: false, // unknown until next outcome evaluation
-            });
+    let newRegHistory = metacognition.regulationHistory.map((record) => ({
+        ...record,
+        remainingTurns: record.remainingTurns !== undefined
+            ? Math.max(0, record.remainingTurns - 1)
+            : record.remainingTurns,
+    }));
+    if (assessment.regulationFeedback) {
+        const targetIndex = [...newRegHistory]
+            .map((record, index) => ({ record, index }))
+            .reverse()
+            .find(({ record }) => record.targetMetric === assessment.regulationFeedback?.targetMetric
+            && record.gapBefore !== undefined
+            && record.effect === undefined)?.index;
+        if (targetIndex !== undefined) {
+            const record = newRegHistory[targetIndex];
+            newRegHistory[targetIndex] = {
+                ...record,
+                effective: assessment.regulationFeedback.effect === "converging",
+                gapLatest: assessment.regulationFeedback.gapNow,
+                effect: assessment.regulationFeedback.effect,
+            };
         }
     }
+    const surfacedSuggestion = assessment.regulationSuggestions.find((suggestion) => suggestion.confidence >= 0.5);
+    if (surfacedSuggestion) {
+        newRegHistory.push({
+            strategy: surfacedSuggestion.strategy,
+            timestamp: now,
+            effective: false,
+            action: surfacedSuggestion.action,
+            horizonTurns: surfacedSuggestion.horizonTurns,
+            remainingTurns: surfacedSuggestion.horizonTurns,
+            targetMetric: surfacedSuggestion.targetMetric,
+            targetValue: surfacedSuggestion.targetValue,
+            gapBefore: surfacedSuggestion.gapBefore,
+            gapLatest: surfacedSuggestion.gapBefore,
+        });
+    }
     // Trim to max
     if (newRegHistory.length > MAX_REGULATION_HISTORY) {
         newRegHistory = newRegHistory.slice(newRegHistory.length - MAX_REGULATION_HISTORY);
@@ -578,6 +709,7 @@ export function updateMetacognitiveState(metacognition, assessment) {
         defensePatterns: newDefensePatterns,
         avgEmotionalConfidence: newAvgConfidence,
         totalAssessments: n + 1,
+        lastRegulationFeedback: assessment.regulationFeedback,
     };
 }
 // ── Display Labels ───────────────────────────────────────────

package/dist/prompt.d.ts

@@ -15,6 +15,8 @@ export declare function buildDynamicContext(state: PsycheState, userId?: string,
     autonomicDescription?: string;
     autonomicState?: AutonomicState;
     primarySystemsDescription?: string;
+    subjectivityContext?: string;
+    responseContractContext?: string;
     policyContext?: string;
 }): string;
 /**
@@ -68,5 +70,7 @@ export declare function buildCompactContext(state: PsycheState, userId?: string,
     autonomicDescription?: string;
     autonomicState?: AutonomicState;
     primarySystemsDescription?: string;
+    subjectivityContext?: string;
+    responseContractContext?: string;
     policyContext?: string;
 }): string;