usesteady 0.1.0-alpha.1

package/dist/src/interaction/guidance-order.js

@@ -0,0 +1,131 @@
+/**
+ * applyGuidanceOrdering — session-aware guidance step ordering.
+ *
+ * This is Phase B2 of session memory alignment. It takes a finalized
+ * GuidancePayload and applies two purely presentational adjustments based
+ * on observedIntentPatterns from the InteractionContract:
+ *
+ *   1. Step type ordering: read_first always before use_exact_format (defensive).
+ *   2. Label emphasis: when the user is familiar with a category
+ *      (≥ FAMILIARITY_THRESHOLD observations), the read_first label
+ *      shortens to action-first form (drops "first" — they know the flow).
+ *
+ * ── HARD INVARIANTS (must never be violated) ─────────────────────────────────
+ *
+ *   1. Step count never changes. No step is added. No step is removed.
+ *   2. missing[] is never modified.
+ *   3. interpretation (category, confidence, summary, basis) is never modified.
+ *   4. mode, reason, signal, intentState are NOT touched (not in this type).
+ *   5. Counts may only affect ordering and label text — never content truth.
+ *   6. A required safe step (read_first) is never suppressed.
+ *   7. If counts tie across categories, ordering is deterministic (stable sort).
+ *   8. Label changes use only the current guidance's interpretation category.
+ *      A high text_change count never alters a visual_color label.
+ *
+ * ── This function is purely presentational ───────────────────────────────────
+ *
+ * It is called after all intake decisions are made. It cannot and must not
+ * feed back into PRV, safety, context alignment, disambiguation, completion,
+ * response planning, or interpretation category/confidence.
+ */
+/**
+ * Number of same-category guided recovery observations required before
+ * the read_first label switches to the shorter, action-first form.
+ *
+ * Below threshold → default label (explains the "why" for new users).
+ * At or above threshold → familiar label (shorter, action-first).
+ */
+export const FAMILIARITY_THRESHOLD = 3;
+/**
+ * Preferred sort order for step types.
+ * read_first is always promoted to the front.
+ * add_missing_field stays in the middle.
+ * use_exact_format is last.
+ *
+ * This is a defensive guarantee — the bridge already produces this order,
+ * but this makes it an explicit, tested property of every guidance payload.
+ */
+const STEP_TYPE_ORDER = {
+    read_first: 0,
+    add_missing_field: 1,
+    use_exact_format: 2,
+};
+/**
+ * Shorter, action-first read_first labels for users familiar with the flow.
+ * Applied only when patterns[category] >= FAMILIARITY_THRESHOLD.
+ *
+ * Default labels contain "first" as a cue for new users ("Read the file FIRST").
+ * Familiar labels drop that cue — experienced users already know the order.
+ */
+const FAMILIAR_READ_FIRST_LABELS = {
+    visual_color: 'Find the current color in the component file: read "<file>"',
+    text_change: 'Find the current text in the file: read "<file>"',
+    config_change: 'Find the current setting in the config file: read "<file>"',
+};
+/**
+ * Apply session-aware ordering to a GuidancePayload.
+ *
+ * Returns a new GuidancePayload with:
+ *   - nextSteps sorted by type (read_first → add_missing_field → use_exact_format)
+ *   - read_first label adjusted to familiar form when patterns[category] >= 3
+ *
+ * All other fields (missing, interpretation, reason) are returned unchanged.
+ *
+ * This is a pure function: deterministic, no side effects.
+ */
+export function applyGuidanceOrdering(guidance, patterns) {
+    const category = guidance.interpretation?.category;
+    const isFamiliar = isFamiliarCategory(category, patterns);
+    // Step 1: Sort by type. Stable sort preserves relative order within type.
+    const sorted = sortByStepType(guidance.nextSteps);
+    // Step 2: Adjust read_first labels for familiar categories only.
+    const adjusted = isFamiliar ? adjustReadFirstLabels(sorted, category) : sorted;
+    // Return with only nextSteps replaced. Everything else is unchanged.
+    if (adjusted === guidance.nextSteps) {
+        return guidance;
+    }
+    return {
+        ...guidance,
+        nextSteps: adjusted,
+    };
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function isFamiliarCategory(category, patterns) {
+    if (category === undefined || category === "unknown" || category === "workflow_operation")
+        return false;
+    return patterns[category] >= FAMILIARITY_THRESHOLD;
+}
+function sortByStepType(steps) {
+    // Already sorted? Return the same reference (no allocation).
+    if (isAlreadySorted(steps))
+        return steps;
+    // Stable sort: spread to mutable, sort with index as tiebreaker.
+    return [...steps].sort((a, b) => {
+        const diff = STEP_TYPE_ORDER[a.type] - STEP_TYPE_ORDER[b.type];
+        if (diff !== 0)
+            return diff;
+        // Same type — preserve original order (stable).
+        return steps.indexOf(a) - steps.indexOf(b);
+    });
+}
+function isAlreadySorted(steps) {
+    for (let i = 1; i < steps.length; i++) {
+        if (STEP_TYPE_ORDER[steps[i - 1].type] > STEP_TYPE_ORDER[steps[i].type]) {
+            return false;
+        }
+    }
+    return true;
+}
+function adjustReadFirstLabels(steps, category) {
+    const familiarLabel = FAMILIAR_READ_FIRST_LABELS[category];
+    if (familiarLabel === undefined)
+        return steps;
+    // Only rewrite if there are read_first steps to adjust.
+    const hasReadFirst = steps.some(s => s.type === "read_first");
+    if (!hasReadFirst)
+        return steps;
+    return steps.map(step => step.type === "read_first"
+        ? { ...step, label: familiarLabel }
+        : step);
+}
+//# sourceMappingURL=guidance-order.js.map

package/dist/src/interaction/guidance-order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guidance-order.js","sourceRoot":"","sources":["../../../src/interaction/guidance-order.ts"],"names":[],"mappings":"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"}

package/dist/src/interaction/observe.d.ts

@@ -0,0 +1,57 @@
+/**
+ * observeIntentPattern — pure gate function for session observation.
+ *
+ * This function decides whether the current pipeline result warrants
+ * emitting an intent observation event to update the InteractionContract.
+ *
+ * ── Why this gate exists ────────────────────────────────────────────────────
+ *
+ * Session memory must only track meaningful guided interpretations — not
+ * generic inputs, incomplete completions, or unclassified vague noise.
+ *
+ * Without this gate, the observed counts would be contaminated by:
+ *   - inputs that short-circuited early (PRV, safety, context)
+ *   - inputs the bridge never evaluated
+ *   - execute / clarify / refuse flows that have nothing to learn from
+ *
+ * ── Hard invariants (must never be violated) ────────────────────────────────
+ *
+ *   1. No event fires unless result.mode === "guide".
+ *      Execution, refusal, and clarification flows are excluded.
+ *
+ *   2. No event fires unless result.guidance?.interpretation is defined.
+ *      The bridge must have produced a classification.
+ *
+ *   3. No event fires unless trace.bridgeFired === true.
+ *      This is the explicit confirmation that the bridge ran and succeeded.
+ *      If no trace is provided, this condition is not met — no event fires.
+ *
+ *   4. No event fires for category "unknown".
+ *      Only the three meaningful categories (visual_color, text_change,
+ *      config_change) produce observation events.
+ *
+ *   5. The returned event is advisory only.
+ *      It must flow through applyInteractionEvent() before any contract
+ *      is updated. It does not mutate anything itself.
+ *
+ *   6. This function does not affect and must never be used to infer:
+ *        - mode, intentState, responseMode
+ *        - safety verdict, PRV result
+ *        - completion result, interpretation category/confidence
+ */
+import type { DebugTrace } from "../intake/trace.js";
+import type { IntakeResult } from "../intake/types.js";
+import type { InteractionEvent } from "./types.js";
+/**
+ * Evaluate whether the pipeline result warrants an intent observation event.
+ *
+ * Returns an InteractionEvent if all four hard conditions are met:
+ *   1. result.mode === "guide"
+ *   2. result.guidance.interpretation is defined
+ *   3. trace.bridgeFired === true
+ *   4. interpretation.category is one of: visual_color, text_change, config_change
+ *
+ * Returns null in all other cases. Null is a valid, correct response.
+ */
+export declare function observeIntentPattern(result: IntakeResult, trace?: DebugTrace): InteractionEvent | null;
+//# sourceMappingURL=observe.d.ts.map

package/dist/src/interaction/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../../src/interaction/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,YAAY,EACpB,KAAK,CAAC,EAAE,UAAU,GACjB,gBAAgB,GAAG,IAAI,CA0BzB"}

package/dist/src/interaction/observe.js

@@ -0,0 +1,77 @@
+/**
+ * observeIntentPattern — pure gate function for session observation.
+ *
+ * This function decides whether the current pipeline result warrants
+ * emitting an intent observation event to update the InteractionContract.
+ *
+ * ── Why this gate exists ────────────────────────────────────────────────────
+ *
+ * Session memory must only track meaningful guided interpretations — not
+ * generic inputs, incomplete completions, or unclassified vague noise.
+ *
+ * Without this gate, the observed counts would be contaminated by:
+ *   - inputs that short-circuited early (PRV, safety, context)
+ *   - inputs the bridge never evaluated
+ *   - execute / clarify / refuse flows that have nothing to learn from
+ *
+ * ── Hard invariants (must never be violated) ────────────────────────────────
+ *
+ *   1. No event fires unless result.mode === "guide".
+ *      Execution, refusal, and clarification flows are excluded.
+ *
+ *   2. No event fires unless result.guidance?.interpretation is defined.
+ *      The bridge must have produced a classification.
+ *
+ *   3. No event fires unless trace.bridgeFired === true.
+ *      This is the explicit confirmation that the bridge ran and succeeded.
+ *      If no trace is provided, this condition is not met — no event fires.
+ *
+ *   4. No event fires for category "unknown".
+ *      Only the three meaningful categories (visual_color, text_change,
+ *      config_change) produce observation events.
+ *
+ *   5. The returned event is advisory only.
+ *      It must flow through applyInteractionEvent() before any contract
+ *      is updated. It does not mutate anything itself.
+ *
+ *   6. This function does not affect and must never be used to infer:
+ *        - mode, intentState, responseMode
+ *        - safety verdict, PRV result
+ *        - completion result, interpretation category/confidence
+ */
+/**
+ * Evaluate whether the pipeline result warrants an intent observation event.
+ *
+ * Returns an InteractionEvent if all four hard conditions are met:
+ *   1. result.mode === "guide"
+ *   2. result.guidance.interpretation is defined
+ *   3. trace.bridgeFired === true
+ *   4. interpretation.category is one of: visual_color, text_change, config_change
+ *
+ * Returns null in all other cases. Null is a valid, correct response.
+ */
+export function observeIntentPattern(result, trace) {
+    // Gate 1: only guide mode produces meaningful observations.
+    if (result.mode !== "guide") {
+        return null;
+    }
+    // Gate 2: bridge must have produced an interpretation.
+    const interpretation = result.guidance?.interpretation;
+    if (interpretation === undefined) {
+        return null;
+    }
+    // Gate 3: explicit trace confirmation that the bridge actually fired.
+    // If trace is absent, bridgeFired is unknown — default to safe (no event).
+    if (trace?.bridgeFired !== true) {
+        return null;
+    }
+    // Gate 4: map meaningful categories to observation events.
+    // "unknown" category is excluded — it carries no useful session signal.
+    switch (interpretation.category) {
+        case "visual_color": return { type: "color_intent_observed" };
+        case "text_change": return { type: "text_intent_observed" };
+        case "config_change": return { type: "config_intent_observed" };
+        default: return null;
+    }
+}
+//# sourceMappingURL=observe.js.map

package/dist/src/interaction/observe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../../src/interaction/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAMH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAoB,EACpB,KAAkB;IAElB,4DAA4D;IAC5D,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,uDAAuD;IACvD,MAAM,cAAc,GAAG,MAAM,CAAC,QAAQ,EAAE,cAAc,CAAC;IACvD,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,sEAAsE;IACtE,2EAA2E;IAC3E,IAAI,KAAK,EAAE,WAAW,KAAK,IAAI,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,2DAA2D;IAC3D,wEAAwE;IACxE,QAAQ,cAAc,CAAC,QAAQ,EAAE,CAAC;QAChC,KAAK,cAAc,CAAC,CAAE,OAAO,EAAE,IAAI,EAAE,uBAAuB,EAAE,CAAC;QAC/D,KAAK,aAAa,CAAC,CAAG,OAAO,EAAE,IAAI,EAAE,sBAAsB,EAAE,CAAC;QAC9D,KAAK,eAAe,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,wBAAwB,EAAE,CAAC;QAChE,OAAO,CAAC,CAAc,OAAO,IAAI,CAAC;IACpC,CAAC;AACH,CAAC"}

package/dist/src/interaction/selectors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Interaction Contract selectors.
+ *
+ * Pure functions that extract policy decisions from a contract.
+ * Nothing should read contract fields directly outside this module.
+ */
+import type { InteractionContract } from "./types.js";
+export declare function getAmbiguityPolicy(contract: InteractionContract): InteractionContract["ambiguityMode"];
+export declare function getExplanationPolicy(contract: InteractionContract): InteractionContract["explanationMode"];
+export declare function getUnsupportedGuidancePolicy(contract: InteractionContract): InteractionContract["unsupportedGuidanceMode"];
+/**
+ * Returns true if ambiguity should be treated conservatively
+ * (i.e., always ask rather than guess).
+ */
+export declare function isConservativeAmbiguityMode(contract: InteractionContract): boolean;
+//# sourceMappingURL=selectors.d.ts.map

package/dist/src/interaction/selectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.d.ts","sourceRoot":"","sources":["../../../src/interaction/selectors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,mBAAmB,GAC5B,mBAAmB,CAAC,eAAe,CAAC,CAEtC;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,mBAAmB,GAC5B,mBAAmB,CAAC,iBAAiB,CAAC,CAExC;AAED,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,mBAAmB,GAC5B,mBAAmB,CAAC,yBAAyB,CAAC,CAEhD;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAElF"}

package/dist/src/interaction/selectors.js

@@ -0,0 +1,23 @@
+/**
+ * Interaction Contract selectors.
+ *
+ * Pure functions that extract policy decisions from a contract.
+ * Nothing should read contract fields directly outside this module.
+ */
+export function getAmbiguityPolicy(contract) {
+    return contract.ambiguityMode;
+}
+export function getExplanationPolicy(contract) {
+    return contract.explanationMode;
+}
+export function getUnsupportedGuidancePolicy(contract) {
+    return contract.unsupportedGuidanceMode;
+}
+/**
+ * Returns true if ambiguity should be treated conservatively
+ * (i.e., always ask rather than guess).
+ */
+export function isConservativeAmbiguityMode(contract) {
+    return contract.ambiguityMode === "conservative";
+}
+//# sourceMappingURL=selectors.js.map

package/dist/src/interaction/selectors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.js","sourceRoot":"","sources":["../../../src/interaction/selectors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,UAAU,kBAAkB,CAChC,QAA6B;IAE7B,OAAO,QAAQ,CAAC,aAAa,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,QAA6B;IAE7B,OAAO,QAAQ,CAAC,eAAe,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,4BAA4B,CAC1C,QAA6B;IAE7B,OAAO,QAAQ,CAAC,uBAAuB,CAAC;AAC1C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CAAC,QAA6B;IACvE,OAAO,QAAQ,CAAC,aAAa,KAAK,cAAc,CAAC;AACnD,CAAC"}

package/dist/src/interaction/types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Interaction Contract types.
+ *
+ * The InteractionContract is a lightweight, immutable record that captures
+ * how a subject (user/session) interacts with UseSteady.
+ *
+ * It is:
+ *   - Deterministic: same events produce same transitions
+ *   - Pure: no I/O, no side effects in updater
+ *   - Not a profile: no personal data, no identity tracking
+ *   - Not persistent: in-memory only in this phase
+ *
+ * The source field tracks confidence:
+ *   - "default"        → never adjusted
+ *   - "observed"       → adjusted from behavioral signals
+ *   - "user_confirmed" → explicitly set by user action
+ *
+ * ── observedIntentPatterns (advisory session signal) ─────────────────────────
+ *
+ * Records how many times each intent category was seen in this session.
+ * These counts are produced only when the Intent Interpretation Bridge
+ * fired AND produced a classification (bridgeFired: true in DebugTrace).
+ *
+ * CONTRACTS (non-negotiable, must not be violated):
+ *
+ *   1. observedIntentPatterns is advisory only.
+ *      It records what was observed. It adapts nothing automatically.
+ *
+ *   2. It may only ever affect (in Phase B2, not before):
+ *        - guidance ordering
+ *        - guidance emphasis
+ *        - example ordering
+ *
+ *   3. It must NEVER affect:
+ *        - PRV result
+ *        - Safety Gate verdict
+ *        - Context Alignment result
+ *        - Disambiguation result
+ *        - Completion result
+ *        - Response mode / intentState
+ *        - Interpretation category or confidence
+ *
+ *   4. No observation event may fire unless bridgeFired === true in the trace.
+ *      This ensures counts track meaningful guided interpretations only —
+ *      not generic noise, vague inputs, or incomplete completions.
+ */
+export type ObservedIntentPatterns = {
+    /**
+     * Number of times visual_color was the classified intent category
+     * in a guided_recovery flow where bridgeFired === true.
+     */
+    readonly visual_color: number;
+    /**
+     * Number of times text_change was the classified intent category
+     * in a guided_recovery flow where bridgeFired === true.
+     */
+    readonly text_change: number;
+    /**
+     * Number of times config_change was the classified intent category
+     * in a guided_recovery flow where bridgeFired === true.
+     */
+    readonly config_change: number;
+};
+export type InteractionContract = {
+    readonly version: 1;
+    readonly subjectId: string;
+    readonly ambiguityMode: "conservative" | "balanced" | "fast";
+    readonly explanationMode: "plain_first" | "technical_first" | "mixed";
+    readonly unsupportedGuidanceMode: "syntax_first" | "examples_first" | "stepwise";
+    readonly updatedAt: string;
+    readonly source: "default" | "user_confirmed" | "observed";
+    /**
+     * Advisory session signal — see contracts above.
+     * All counts default to 0. Incremented by observation events only.
+     * Phase B2 (not yet built) will read these to order guidance.
+     */
+    readonly observedIntentPatterns: ObservedIntentPatterns;
+};
+/**
+ * Events that may update the contract.
+ *
+ * Events are behavioral observations, not explicit user preferences.
+ * Only high-signal, low-ambiguity events are defined.
+ *
+ * ── Observation events (Phase B1) ────────────────────────────────────────────
+ *
+ * color_intent_observed, text_intent_observed, config_intent_observed
+ *   → Fire only when: mode === "guide" AND guidance.interpretation exists
+ *     AND trace.bridgeFired === true.
+ *   → Increment the corresponding observedIntentPatterns count.
+ *   → See observeIntentPattern() in interaction/observe.ts for the gating logic.
+ */
+export type InteractionEvent = {
+    readonly type: "misinterpretation_corrected";
+} | {
+    readonly type: "unsupported_recovered";
+    readonly recoveryStyle: "syntax_hint" | "example_used" | "stepwise_followed";
+} | {
+    readonly type: "color_intent_observed";
+} | {
+    readonly type: "text_intent_observed";
+} | {
+    readonly type: "config_intent_observed";
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/interaction/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/interaction/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,MAAM,MAAM,sBAAsB,GAAG;IACnC;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAG,MAAM,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAI,MAAM,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,cAAc,GAAG,UAAU,GAAG,MAAM,CAAC;IAC7D,QAAQ,CAAC,eAAe,EAAE,aAAa,GAAG,iBAAiB,GAAG,OAAO,CAAC;IACtE,QAAQ,CAAC,uBAAuB,EAAE,cAAc,GAAG,gBAAgB,GAAG,UAAU,CAAC;IACjF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,gBAAgB,GAAG,UAAU,CAAC;IAE3D;;;;OAIG;IACH,QAAQ,CAAC,sBAAsB,EAAE,sBAAsB,CAAC;CACzD,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,aAAa,GAAG,cAAc,GAAG,mBAAmB,CAAA;CAAE,GACxH;IAAE,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAA;CAAE,GAC1C;IAAE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAA;CAAE,GACzC;IAAE,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAA;CAAE,CAAC"}

package/dist/src/interaction/types.js

@@ -0,0 +1,48 @@
+/**
+ * Interaction Contract types.
+ *
+ * The InteractionContract is a lightweight, immutable record that captures
+ * how a subject (user/session) interacts with UseSteady.
+ *
+ * It is:
+ *   - Deterministic: same events produce same transitions
+ *   - Pure: no I/O, no side effects in updater
+ *   - Not a profile: no personal data, no identity tracking
+ *   - Not persistent: in-memory only in this phase
+ *
+ * The source field tracks confidence:
+ *   - "default"        → never adjusted
+ *   - "observed"       → adjusted from behavioral signals
+ *   - "user_confirmed" → explicitly set by user action
+ *
+ * ── observedIntentPatterns (advisory session signal) ─────────────────────────
+ *
+ * Records how many times each intent category was seen in this session.
+ * These counts are produced only when the Intent Interpretation Bridge
+ * fired AND produced a classification (bridgeFired: true in DebugTrace).
+ *
+ * CONTRACTS (non-negotiable, must not be violated):
+ *
+ *   1. observedIntentPatterns is advisory only.
+ *      It records what was observed. It adapts nothing automatically.
+ *
+ *   2. It may only ever affect (in Phase B2, not before):
+ *        - guidance ordering
+ *        - guidance emphasis
+ *        - example ordering
+ *
+ *   3. It must NEVER affect:
+ *        - PRV result
+ *        - Safety Gate verdict
+ *        - Context Alignment result
+ *        - Disambiguation result
+ *        - Completion result
+ *        - Response mode / intentState
+ *        - Interpretation category or confidence
+ *
+ *   4. No observation event may fire unless bridgeFired === true in the trace.
+ *      This ensures counts track meaningful guided interpretations only —
+ *      not generic noise, vague inputs, or incomplete completions.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/interaction/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/interaction/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG"}

package/dist/src/interaction/updater.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Interaction Contract updater — pure function.
+ *
+ * applyInteractionEvent(contract, event) → nextContract
+ *
+ * Rules:
+ *   - Never mutates. Returns a new contract object.
+ *   - Transitions are deterministic: same event always produces same delta.
+ *   - Source becomes "observed" after any event-driven update.
+ *   - updatedAt is set by the caller via timestamp argument (keeps function pure).
+ *
+ * ── Observation events (visual_color, text_change, config_change) ─────────────
+ *
+ * These increment the corresponding observedIntentPatterns count.
+ * All other contract fields are left unchanged.
+ *
+ * ADVISORY ONLY — see InteractionContract type for the full contract.
+ * These counts may never influence mode, safety, completion, or interpretation.
+ */
+import type { InteractionContract, InteractionEvent } from "./types.js";
+export declare function applyInteractionEvent(contract: InteractionContract, event: InteractionEvent, updatedAt?: string): InteractionContract;
+//# sourceMappingURL=updater.d.ts.map

package/dist/src/interaction/updater.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updater.d.ts","sourceRoot":"","sources":["../../../src/interaction/updater.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAExE,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,gBAAgB,EACvB,SAAS,GAAE,MAAiC,GAC3C,mBAAmB,CA0DrB"}

package/dist/src/interaction/updater.js

@@ -0,0 +1,87 @@
+/**
+ * Interaction Contract updater — pure function.
+ *
+ * applyInteractionEvent(contract, event) → nextContract
+ *
+ * Rules:
+ *   - Never mutates. Returns a new contract object.
+ *   - Transitions are deterministic: same event always produces same delta.
+ *   - Source becomes "observed" after any event-driven update.
+ *   - updatedAt is set by the caller via timestamp argument (keeps function pure).
+ *
+ * ── Observation events (visual_color, text_change, config_change) ─────────────
+ *
+ * These increment the corresponding observedIntentPatterns count.
+ * All other contract fields are left unchanged.
+ *
+ * ADVISORY ONLY — see InteractionContract type for the full contract.
+ * These counts may never influence mode, safety, completion, or interpretation.
+ */
+export function applyInteractionEvent(contract, event, updatedAt = new Date().toISOString()) {
+    switch (event.type) {
+        case "misinterpretation_corrected":
+            // User corrected a misinterpretation → be more conservative with ambiguity.
+            return {
+                ...contract,
+                ambiguityMode: trendConservative(contract.ambiguityMode),
+                source: "observed",
+                updatedAt,
+            };
+        case "unsupported_recovered":
+            // User successfully recovered from unsupported input → note which style helped.
+            return {
+                ...contract,
+                unsupportedGuidanceMode: recoveryStyleToMode(event.recoveryStyle),
+                source: "observed",
+                updatedAt,
+            };
+        // ── Observation events ──────────────────────────────────────────────────
+        // Increment one observed intent pattern count. No other field changes.
+        // These events are produced only by observeIntentPattern() after verifying
+        // that bridgeFired === true in the debug trace.
+        case "color_intent_observed":
+            return {
+                ...contract,
+                observedIntentPatterns: {
+                    ...contract.observedIntentPatterns,
+                    visual_color: contract.observedIntentPatterns.visual_color + 1,
+                },
+                source: "observed",
+                updatedAt,
+            };
+        case "text_intent_observed":
+            return {
+                ...contract,
+                observedIntentPatterns: {
+                    ...contract.observedIntentPatterns,
+                    text_change: contract.observedIntentPatterns.text_change + 1,
+                },
+                source: "observed",
+                updatedAt,
+            };
+        case "config_intent_observed":
+            return {
+                ...contract,
+                observedIntentPatterns: {
+                    ...contract.observedIntentPatterns,
+                    config_change: contract.observedIntentPatterns.config_change + 1,
+                },
+                source: "observed",
+                updatedAt,
+            };
+    }
+}
+// ─── Transition helpers ───────────────────────────────────────────────────────
+function trendConservative(current) {
+    if (current === "fast")
+        return "balanced";
+    return "conservative";
+}
+function recoveryStyleToMode(style) {
+    switch (style) {
+        case "syntax_hint": return "syntax_first";
+        case "example_used": return "examples_first";
+        case "stepwise_followed": return "stepwise";
+    }
+}
+//# sourceMappingURL=updater.js.map

package/dist/src/interaction/updater.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updater.js","sourceRoot":"","sources":["../../../src/interaction/updater.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,MAAM,UAAU,qBAAqB,CACnC,QAA6B,EAC7B,KAAuB,EACvB,YAAoB,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;IAE5C,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,6BAA6B;YAChC,4EAA4E;YAC5E,OAAO;gBACL,GAAG,QAAQ;gBACX,aAAa,EAAE,iBAAiB,CAAC,QAAQ,CAAC,aAAa,CAAC;gBACxD,MAAM,EAAS,UAAU;gBACzB,SAAS;aACV,CAAC;QAEJ,KAAK,uBAAuB;YAC1B,gFAAgF;YAChF,OAAO;gBACL,GAAG,QAAQ;gBACX,uBAAuB,EAAE,mBAAmB,CAAC,KAAK,CAAC,aAAa,CAAC;gBACjE,MAAM,EAAmB,UAAU;gBACnC,SAAS;aACV,CAAC;QAEJ,2EAA2E;QAC3E,uEAAuE;QACvE,2EAA2E;QAC3E,gDAAgD;QAEhD,KAAK,uBAAuB;YAC1B,OAAO;gBACL,GAAG,QAAQ;gBACX,sBAAsB,EAAE;oBACtB,GAAG,QAAQ,CAAC,sBAAsB;oBAClC,YAAY,EAAE,QAAQ,CAAC,sBAAsB,CAAC,YAAY,GAAG,CAAC;iBAC/D;gBACD,MAAM,EAAK,UAAU;gBACrB,SAAS;aACV,CAAC;QAEJ,KAAK,sBAAsB;YACzB,OAAO;gBACL,GAAG,QAAQ;gBACX,sBAAsB,EAAE;oBACtB,GAAG,QAAQ,CAAC,sBAAsB;oBAClC,WAAW,EAAE,QAAQ,CAAC,sBAAsB,CAAC,WAAW,GAAG,CAAC;iBAC7D;gBACD,MAAM,EAAK,UAAU;gBACrB,SAAS;aACV,CAAC;QAEJ,KAAK,wBAAwB;YAC3B,OAAO;gBACL,GAAG,QAAQ;gBACX,sBAAsB,EAAE;oBACtB,GAAG,QAAQ,CAAC,sBAAsB;oBAClC,aAAa,EAAE,QAAQ,CAAC,sBAAsB,CAAC,aAAa,GAAG,CAAC;iBACjE;gBACD,MAAM,EAAK,UAAU;gBACrB,SAAS;aACV,CAAC;IACN,CAAC;AACH,CAAC;AAED,iFAAiF;AAEjF,SAAS,iBAAiB,CACxB,OAA6C;IAE7C,IAAI,OAAO,KAAK,MAAM;QAAE,OAAO,UAAU,CAAC;IAC1C,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,SAAS,mBAAmB,CAC1B,KAA2D;IAE3D,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,aAAa,CAAC,CAAO,OAAO,cAAc,CAAC;QAChD,KAAK,cAAc,CAAC,CAAM,OAAO,gBAAgB,CAAC;QAClD,KAAK,mBAAmB,CAAC,CAAC,OAAO,UAAU,CAAC;IAC9C,CAAC;AACH,CAAC"}