@dory-agentic/dory-agentic-sdk 0.2.0

package/dist/lfs/config.js

@@ -0,0 +1,34 @@
+export const LFS_CONFIG = {
+    BYPASS_THRESHOLD: 0.25,
+    PREFLIGHT_PASS_THRU_THRESHOLD: 0.50,
+    DECAY_BASELINE_FACTOR: 1.2,
+    ALPHA_MASS_PENALTY: 0.35,
+    /** When UI memory cap is 100%, effective eviction cap uses this fraction of contextMax. */
+    PHYSICAL_FIREBREAK: 0.95,
+    NATIVE_CONTEXT_FRACTION: 0.82,
+    LFS_API_SEND_FRACTION: 0.80,
+    OUTPUT_RESERVE_FRACTION: 0.05,
+    OUTPUT_RESERVE_FLOOR: 2048,
+    OUTPUT_RESERVE_CEILING: 16384,
+};
+export const LFS_MEMORY_CAP = {
+    DEFAULT: 0.70,
+    MIN: 0.50,
+    MAX: 0.99,
+};
+export function clampMemoryCapFraction(fraction) {
+    return Math.min(LFS_MEMORY_CAP.MAX, Math.max(LFS_MEMORY_CAP.MIN, fraction));
+}
+/** UI 100% maps to PHYSICAL_FIREBREAK so provider wrappers never hit hard truncation. */
+export function effectiveMemoryCapFraction(uiFraction) {
+    const clamped = clampMemoryCapFraction(uiFraction);
+    // Preserve the UI semantic that "100%" maps to a physical firebreak.
+    if (uiFraction >= 1.0 || clamped >= 1.0) {
+        return LFS_CONFIG.PHYSICAL_FIREBREAK;
+    }
+    return clamped;
+}
+export function computeOutputReserveTokens(contextMax) {
+    const proportional = Math.floor(contextMax * LFS_CONFIG.OUTPUT_RESERVE_FRACTION);
+    return Math.min(Math.max(LFS_CONFIG.OUTPUT_RESERVE_FLOOR, proportional), LFS_CONFIG.OUTPUT_RESERVE_CEILING);
+}

package/dist/lfs/contextAdapter.d.ts

@@ -0,0 +1,5 @@
+import type { PrepareStepInput, PrepareStepOutput } from "./types";
+export declare class LfsContextAdapter {
+    prepareStep(input: PrepareStepInput): Promise<PrepareStepOutput>;
+}
+//# sourceMappingURL=contextAdapter.d.ts.map

package/dist/lfs/contextAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextAdapter.d.ts","sourceRoot":"","sources":["../../src/lfs/contextAdapter.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAqDnE,qBAAa,iBAAiB;IACtB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CA8HvE"}

package/dist/lfs/contextAdapter.js

@@ -0,0 +1,161 @@
+import { LFS_CONFIG } from "./config";
+import { chunkMessageTurn, calculateDynamicChunkSize } from "./chunkManager";
+import { calculateCreditBudget, initializeForgetScoresMidConversation, } from "./memoryEngine";
+import { determineExecutionLane } from "./preflightRouter";
+import { executeParitySwap } from "./paritySwapper";
+import { resolveLfsRuntimeConfig } from "./runtimeConfig";
+import { getOrCreateSessionState, updateSessionHistory } from "./sessionStore";
+import { estimateMessagesTokens, estimateTextTokens } from "./tokenCounter";
+import { upsertChunkVector } from "./vectorDb";
+import { formatHistoryForModel } from "../history/messageManifest";
+import { buildLfsRemindClause } from "../tools/remind";
+function buildTurnSystemPrompt(params) {
+    if (params.lane === "standard" || !params.isMmuActive) {
+        return `You are a technical software engineering assistant in the ${params.lane.toUpperCase()} lane.`;
+    }
+    return "You are a cognitive memory manager in the OPTIMIZED lane.";
+}
+function latestUserQuery(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role === "user" && messages[i].content?.trim()) {
+            return messages[i].content;
+        }
+    }
+    return messages[messages.length - 1]?.content ?? "";
+}
+async function ensureChunksForNewMessages(params) {
+    const maxChunk = calculateDynamicChunkSize(params.contextMax);
+    const updated = [];
+    for (const msg of params.history) {
+        if (msg.role === "user" &&
+            !msg.chunks?.length &&
+            msg.content.trim() &&
+            estimateTextTokens(msg.content) > maxChunk / 2) {
+            const chunks = chunkMessageTurn(msg.id, msg.content, maxChunk, params.turnIndex);
+            for (const chunk of chunks) {
+                await upsertChunkVector(chunk.chunkId, msg.id, chunk.content);
+            }
+            updated.push({ ...msg, chunks });
+        }
+        else {
+            if (msg.chunks) {
+                for (const chunk of msg.chunks) {
+                    if (!chunk.isArchived) {
+                        await upsertChunkVector(chunk.chunkId, msg.id, chunk.content);
+                    }
+                }
+            }
+            updated.push(msg);
+        }
+    }
+    return updated;
+}
+export class LfsContextAdapter {
+    async prepareStep(input) {
+        const runtime = resolveLfsRuntimeConfig({
+            contextMax: input.contextMax,
+            memoryCapFraction: input.memoryCapFraction,
+        });
+        const session = getOrCreateSessionState({
+            sessionId: input.sessionId,
+            contextMax: runtime.contextMax,
+            memoryCapFraction: runtime.memoryCapFraction,
+        });
+        if (input.agentWeights) {
+            session.agentWeights = { ...session.agentWeights, ...input.agentWeights };
+        }
+        if (input.turnIndex != null) {
+            session.turnIndex = input.turnIndex;
+        }
+        else {
+            session.turnIndex += 1;
+        }
+        const mergedHistory = input.replaceSessionHistory
+            ? [...input.incomingMessages]
+            : [...session.fullHistory, ...input.incomingMessages];
+        updateSessionHistory(input.sessionId, mergedHistory);
+        session.memoryCapFraction = runtime.effectiveMemoryCapFraction;
+        if (input.lane === "standard") {
+            const systemPrompt = buildTurnSystemPrompt({ lane: "standard", isMmuActive: false });
+            return {
+                lane: input.lane,
+                executionLane: "PASS_THRU",
+                isMmuActive: false,
+                messagesForModel: formatHistoryForModel(mergedHistory, systemPrompt, {
+                    lane: "standard",
+                    isMmuActive: false,
+                }),
+                systemBlocks: [systemPrompt],
+                session,
+            };
+        }
+        const query = input.query ?? latestUserQuery(mergedHistory);
+        const lastUserMsg = [...mergedHistory].reverse().find((m) => m.role === "user");
+        const activeHistoryTokens = mergedHistory
+            .filter((m) => !m.isArchived && m.role !== "system" && m.id !== lastUserMsg?.id)
+            .reduce((sum, m) => sum + (m.tokenCount || estimateTextTokens(m.content) || 0), 0);
+        const executionLane = determineExecutionLane({
+            activeHistoryTokens,
+            incomingTextLength: lastUserMsg?.content ?? "",
+            contextMax: runtime.contextMax,
+        });
+        let workingHistory = await ensureChunksForNewMessages({
+            history: mergedHistory,
+            contextMax: runtime.contextMax,
+            turnIndex: session.turnIndex,
+        });
+        const coeffs = runtime.coeffs;
+        let activeHistory = executionLane === "ELASTIC_SWAP"
+            ? initializeForgetScoresMidConversation(workingHistory, coeffs)
+            : workingHistory;
+        const activeTokens = estimateMessagesTokens(activeHistory.filter((m) => !m.isArchived && m.role !== "system"));
+        const isMmuActive = executionLane === "ELASTIC_SWAP" &&
+            activeTokens / runtime.contextMax >= LFS_CONFIG.BYPASS_THRESHOLD;
+        if (isMmuActive) {
+            activeHistory = await executeParitySwap({
+                history: activeHistory,
+                longTermMemory: session.longTermMemory,
+                query,
+                agentWeights: session.agentWeights,
+                contextMax: runtime.contextMax,
+                hardBufferCap: coeffs.hardBufferCap,
+                currentTurnIndex: session.turnIndex,
+            });
+        }
+        const tokensBefore = estimateMessagesTokens(activeHistory);
+        const budget = isMmuActive
+            ? calculateCreditBudget(tokensBefore, runtime.contextMax, coeffs.cMax)
+            : 0;
+        const systemPrompt = buildTurnSystemPrompt({ lane: "optimized", isMmuActive });
+        const remindFromSession = buildLfsRemindClause(session);
+        const remindClause = input.benchmarkSuite
+            ? "No tools in benchmark mode."
+            : input.useRemindTool === false
+                ? "No tools this turn — all visible messages are active."
+                : [
+                    remindFromSession,
+                    "REMIND TOOL: Call remind(target) with chunkId or messageId for archived disk summaries when exact raw text is required.",
+                    input.hydrationBeacon ?? "",
+                ]
+                    .filter(Boolean)
+                    .join("\n");
+        const messagesForModel = formatHistoryForModel(activeHistory, systemPrompt, {
+            lane: "optimized",
+            budget: input.benchmarkSuite ? 0 : budget,
+            remindClause,
+            isMmuActive,
+        });
+        updateSessionHistory(input.sessionId, activeHistory);
+        session.longTermMemory = { ...session.longTermMemory };
+        return {
+            lane: input.lane,
+            executionLane,
+            isMmuActive,
+            messagesForModel,
+            systemBlocks: [systemPrompt],
+            session,
+            budget,
+            remindClause,
+        };
+    }
+}

package/dist/lfs/memoryEngine.d.ts

@@ -0,0 +1,108 @@
+import type { AdaptiveMessage, AllocationMap, TurnMemorySnapshot } from './tokenCounter';
+import type { ContextShift } from './memoryParser';
+export type MemoryCoefficients = {
+    contextMax: number;
+    decayBaseline: number;
+    alpha: number;
+    cMax: number;
+    hardBufferCap: number;
+};
+/** User/assistant turns only — excludes agentic traces and archived/system rows. */
+export declare function isConversationalMessage(m: AdaptiveMessage): boolean;
+/** Latest conversational row — the message being sent now (must not decay this turn). */
+export declare function findActiveTurnAnchorId(history: AdaptiveMessage[]): string | null;
+/**
+ * Conversational message immediately BEFORE the active anchor.
+ * - user send → prior assistant/user turn (not the new user message)
+ * - assistant output → prior turn before the user prompt being answered (not that user prompt)
+ */
+export declare function findPredecessorMessageId(history: AdaptiveMessage[]): string | null;
+/** Decay all scorable messages (except the active turn anchor) when the user sends a new message. */
+export declare function applyUserSendDecay(history: AdaptiveMessage[], coeffs: MemoryCoefficients): AdaptiveMessage[];
+/**
+ * Initializes forgetScore values mid-conversation when the MMU scoring engine wakes up.
+ * Based on their mass-driven baseline age.
+ */
+export declare function initializeForgetScoresMidConversation(history: AdaptiveMessage[], coeffs: MemoryCoefficients): AdaptiveMessage[];
+/**
+ * Hydration Displacement Decay — Fluid Context Rebalancing.
+ *
+ * When archived messages are hydrated back into active context, this function
+ * runs a unified decay pass on all existing active messages to prevent the
+ * context window from spiking past the 40% target pressure ceiling.
+ *
+ * Unified Formula:
+ *   Decay_final = [baseline + α*(T_msg/T_max)] * e^(5*(x-0.40)) * (1 + T_hydrated/(T_max*0.40))
+ *
+ * Three lifecycle behaviors emerge naturally:
+ *   Stage 1 (x≈0.15): e^(-1.25)≈0.28 → massive dampener, decay is tiny, plenty of room
+ *   Stage 2 (x≈0.35): e^(-0.25)≈0.77 → smooth tightening, stale messages accelerate toward edge
+ *   Stage 3 (x≈0.45): e^(+0.25)≈1.28 → surgical displacement, non-relevant blocks jump past 1.0
+ *
+ * Hydrated messages receive forgetScore = 0.0 (zero-score memory lock).
+ * Messages that reach forgetScore >= 1.0 should be immediately paged out
+ * (displacement eviction bypasses the normal turnsAtLimit dampening).
+ */
+export declare function applyHydrationDisplacementDecay(params: {
+    activeHistory: AdaptiveMessage[];
+    hydratedTokens: number;
+    hydratedIds: Set<string>;
+    coeffs: MemoryCoefficients;
+}): AdaptiveMessage[];
+export declare function calculateCreditBudget(currentTokens: number, maxTokens: number, cMax: number): number;
+export declare function validateAndApplyCredits(scaledAllocation: AllocationMap, messages: AdaptiveMessage[]): AdaptiveMessage[];
+/** One agentic-loop memory evaluation (credits + snapshot). Decay is handled at user send. */
+export declare function applyAgenticStepMemory(params: {
+    history: AdaptiveMessage[];
+    coeffs: MemoryCoefficients;
+    contextShift: ContextShift;
+    agentWeights: AllocationMap;
+    referencedIds: string[];
+    protectedIds: Set<string>;
+    stepIndex: number;
+    /** Who is "sending" at this memory boundary — drives predecessor decay. */
+    outgoingRole?: 'user' | 'assistant';
+}): {
+    history: AdaptiveMessage[];
+    budget: number;
+    creditsConsumed: number;
+    scaledAllocation: AllocationMap;
+    snapshot: TurnMemorySnapshot;
+    tokens: number;
+};
+export declare function getPressureRatio(tokens: number, contextMax: number): number;
+/**
+ * UI-only suggestion for memory cap slider (does not override user profile at execution).
+ *
+ * Formula:
+ *   contextMax ≤ 16,384  →  0.40
+ *   otherwise             →  min(0.40 + log10(contextMax / 10_000) × 0.15, 0.75)
+ *
+ * Effective ranges:
+ *   10k  → 0.40
+ *   1M   → 0.70
+ *   10M+ → 0.75 (ceiling)
+ */
+export declare function suggestMemoryCapFraction(contextMax: number): number;
+/** @deprecated Use suggestMemoryCapFraction for UI hints; use resolveLfsRuntimeConfig for execution. */
+export declare function calculateCapacityFactor(contextMax: number): number;
+/**
+ * Returns the effective token cap for the given context window and cap fraction.
+ */
+export declare function calculateTargetMemoryCap(contextMax: number, memoryCapFraction?: number): number;
+/**
+ * Normalised pressure against the memory cap (0.0 → ∞).
+ */
+export declare function getNormalizedPressure(activeTokens: number, contextMax: number, memoryCapFraction?: number): number;
+/**
+ * Credit budget with logarithmic floor — guarantees ≥ 10 credits even under
+ * severe context pressure, preventing the agent from going completely silent.
+ *
+ * Formula:
+ *   pressure < 1.0  →  100
+ *   otherwise        →  max(⌊100 / (1 + ln(pressure))⌋, 10)
+ *
+ * Uses the auto-derived cap when called without a hardBufferCap override.
+ */
+export declare function calculateCreditBudgetV2(activeTokens: number, contextMax: number, hardBufferCapOverride?: number): number;
+//# sourceMappingURL=memoryEngine.d.ts.map

package/dist/lfs/memoryEngine.d.ts.map

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

package/dist/lfs/memoryEngine.js

@@ -0,0 +1,322 @@
+import { estimateMessagesTokens, estimateTextTokens } from './tokenCounter';
+import { resolveTurnCredits, buildTurnMemorySnapshot, collectScorableMessageIds, } from './memoryParser';
+/** User/assistant turns only — excludes agentic traces and archived/system rows. */
+export function isConversationalMessage(m) {
+    if (m.isArchived || m.role === 'system' || m.role === 'tool')
+        return false;
+    if (m.stepKind === 'thought' || m.stepKind === 'memory')
+        return false;
+    return m.role === 'user' || m.role === 'assistant';
+}
+/** Latest conversational row — the message being sent now (must not decay this turn). */
+export function findActiveTurnAnchorId(history) {
+    const conv = history.filter(isConversationalMessage);
+    return conv[conv.length - 1]?.id ?? null;
+}
+/**
+ * Conversational message immediately BEFORE the active anchor.
+ * - user send → prior assistant/user turn (not the new user message)
+ * - assistant output → prior turn before the user prompt being answered (not that user prompt)
+ */
+export function findPredecessorMessageId(history) {
+    const conv = history.filter(isConversationalMessage);
+    if (conv.length < 2)
+        return null;
+    return conv[conv.length - 2]?.id ?? null;
+}
+function applyDecayDelta(m, coeffs, decayBaselineActive) {
+    const tokenCount = m.tokenCount || estimateTextTokens(m.content) || 1;
+    const decayApplied = decayBaselineActive + coeffs.alpha * (tokenCount / coeffs.contextMax);
+    const nextScore = Math.min(1.0, (m.forgetScore ?? 0.0) + decayApplied);
+    return {
+        forgetScore: Number(nextScore.toFixed(4)),
+        decayApplied: Number(decayApplied.toFixed(4)),
+    };
+}
+/** Decay all scorable messages (except the active turn anchor) when the user sends a new message. */
+export function applyUserSendDecay(history, coeffs) {
+    const activeAnchorId = findActiveTurnAnchorId(history);
+    // Calculate active tokens size in current context (excluding archived messages and system instructions)
+    const activeTokens = history
+        .filter((m) => !m.isArchived && m.role !== 'system')
+        .reduce((sum, m) => sum + (m.tokenCount || estimateTextTokens(m.content) || 0), 0);
+    const pressure = activeTokens / coeffs.contextMax;
+    // 70% Hard Headroom Buffer Cap Trigger
+    const effectivePressure = pressure > coeffs.hardBufferCap
+        ? pressure * 1.4 // Dynamically steepen the curve to force intense evictions
+        : pressure;
+    const targetPressure = 0.40;
+    const sensitivity = 5.0; // Control stiffness of regulation band
+    // Exponential baseline decay scaling: multiplier is 1.0 at 40% pressure
+    const pressureMultiplier = Math.exp(sensitivity * (effectivePressure - targetPressure));
+    // Bound the decay baseline to prevent extreme behavior (min 0.005, max 0.80)
+    const decayBaselineActive = Math.min(0.80, Math.max(0.005, coeffs.decayBaseline * pressureMultiplier));
+    return history.map((m) => {
+        if (!isConversationalMessage(m) || !m.id || m.id === activeAnchorId)
+            return m;
+        // HYDRATION SHIELD GRACE PERIOD
+        if (m.hydrationGraceTurns && m.hydrationGraceTurns > 0) {
+            return {
+                ...m,
+                forgetScore: 0.0, // Retain perfect memory immunity
+                turnsAtLimit: 0,
+                hydrationGraceTurns: m.hydrationGraceTurns - 1,
+                decayApplied: 0,
+            };
+        }
+        const { forgetScore, decayApplied } = applyDecayDelta(m, coeffs, decayBaselineActive);
+        const turnsAtLimit = forgetScore >= 1.0 ? (m.turnsAtLimit ?? 0) + 1 : 0;
+        // Explicit LFS v4 Displacement tagging
+        if (forgetScore >= 1.0 && !m.isArchived) {
+            return {
+                ...m,
+                forgetScore: 1.0,
+                turnsAtLimit,
+                decayApplied,
+            };
+        }
+        return { ...m, forgetScore, decayApplied, turnsAtLimit };
+    });
+}
+/**
+ * Initializes forgetScore values mid-conversation when the MMU scoring engine wakes up.
+ * Based on their mass-driven baseline age.
+ */
+export function initializeForgetScoresMidConversation(history, coeffs) {
+    const conv = history.filter(isConversationalMessage);
+    const activeAnchorId = findActiveTurnAnchorId(history);
+    return history.map((m) => {
+        if (!isConversationalMessage(m) || !m.id || m.id === activeAnchorId || m.forgetScore !== undefined) {
+            return m;
+        }
+        const idx = conv.findIndex((x) => x.id === m.id);
+        if (idx === -1)
+            return m;
+        const turnsExisted = conv.length - 1 - idx;
+        if (turnsExisted <= 0)
+            return m;
+        const tokenCount = m.tokenCount || estimateTextTokens(m.content) || 1;
+        const baseDecay = coeffs.decayBaseline + coeffs.alpha * (tokenCount / coeffs.contextMax);
+        const initialScore = Math.min(0.95, turnsExisted * baseDecay);
+        return {
+            ...m,
+            forgetScore: Number(initialScore.toFixed(4)),
+            turnsAtLimit: 0,
+        };
+    });
+}
+/**
+ * Hydration Displacement Decay — Fluid Context Rebalancing.
+ *
+ * When archived messages are hydrated back into active context, this function
+ * runs a unified decay pass on all existing active messages to prevent the
+ * context window from spiking past the 40% target pressure ceiling.
+ *
+ * Unified Formula:
+ *   Decay_final = [baseline + α*(T_msg/T_max)] * e^(5*(x-0.40)) * (1 + T_hydrated/(T_max*0.40))
+ *
+ * Three lifecycle behaviors emerge naturally:
+ *   Stage 1 (x≈0.15): e^(-1.25)≈0.28 → massive dampener, decay is tiny, plenty of room
+ *   Stage 2 (x≈0.35): e^(-0.25)≈0.77 → smooth tightening, stale messages accelerate toward edge
+ *   Stage 3 (x≈0.45): e^(+0.25)≈1.28 → surgical displacement, non-relevant blocks jump past 1.0
+ *
+ * Hydrated messages receive forgetScore = 0.0 (zero-score memory lock).
+ * Messages that reach forgetScore >= 1.0 should be immediately paged out
+ * (displacement eviction bypasses the normal turnsAtLimit dampening).
+ */
+export function applyHydrationDisplacementDecay(params) {
+    const { activeHistory, hydratedTokens, hydratedIds, coeffs } = params;
+    const activeAnchorId = findActiveTurnAnchorId(activeHistory);
+    // Current system pressure x = activeTokens / contextMax
+    const activeTokens = activeHistory
+        .filter((m) => !m.isArchived && m.role !== 'system')
+        .reduce((sum, m) => sum + (m.tokenCount || estimateTextTokens(m.content) || 0), 0);
+    const pressure = activeTokens / coeffs.contextMax;
+    // 70% Hard Headroom Buffer Cap Trigger
+    const effectivePressure = pressure > coeffs.hardBufferCap
+        ? pressure * 1.4 // Dynamically steepen the curve to force intense evictions
+        : pressure;
+    const targetCeiling = coeffs.contextMax * 0.40;
+    // Exponential pressure modifier: e^(5.0 * (x - 0.40))
+    const pressureMultiplier = Math.exp(5.0 * (effectivePressure - 0.40));
+    // Hydration volume mass booster: 1 + (T_hydrated / (T_max * 0.40))
+    const hydrationMassBooster = 1 + (hydratedTokens / targetCeiling);
+    return activeHistory.map((m) => {
+        // Skip non-conversational, archived, system messages
+        if (!isConversationalMessage(m) || !m.id)
+            return m;
+        // Active turn anchor: never displace
+        if (m.id === activeAnchorId)
+            return m;
+        // Hydrated messages: zero-score memory lock (protected)
+        if (hydratedIds.has(m.id)) {
+            return { ...m, forgetScore: 0.0, turnsAtLimit: 0, decayApplied: 0 };
+        }
+        // Grace shield protection without decrementing (happens in user send decay)
+        if (m.hydrationGraceTurns && m.hydrationGraceTurns > 0) {
+            return { ...m, forgetScore: 0.0, turnsAtLimit: 0, decayApplied: 0 };
+        }
+        // Unified displacement decay formula
+        const tokenCount = m.tokenCount || estimateTextTokens(m.content) || 1;
+        const baseDecay = coeffs.decayBaseline + (coeffs.alpha * (tokenCount / coeffs.contextMax));
+        const totalTurnDecay = baseDecay * pressureMultiplier * hydrationMassBooster;
+        const newForgetScore = Math.min(1.0, (m.forgetScore ?? 0) + totalTurnDecay);
+        return {
+            ...m,
+            forgetScore: Number(newForgetScore.toFixed(4)),
+            decayApplied: Number(totalTurnDecay.toFixed(4)),
+        };
+    });
+}
+export function calculateCreditBudget(currentTokens, maxTokens, cMax) {
+    const x = currentTokens / maxTokens;
+    return Math.round(cMax * Math.exp(-2.5 * x));
+}
+export function validateAndApplyCredits(scaledAllocation, messages) {
+    return messages.map((m) => {
+        if (m.isArchived || m.role === 'system')
+            return m;
+        const finalCredits = scaledAllocation[m.id] || 0;
+        if (finalCredits <= 0)
+            return m;
+        const tokenCount = m.tokenCount || estimateTextTokens(m.content) || 1;
+        const reduction = finalCredits / Math.sqrt(tokenCount);
+        const nextScore = Math.max(0.0, (m.forgetScore ?? 0.0) - reduction);
+        return {
+            ...m,
+            forgetScore: Number(nextScore.toFixed(4)),
+            turnsAtLimit: 0,
+        };
+    });
+}
+/** One agentic-loop memory evaluation (credits + snapshot). Decay is handled at user send. */
+export function applyAgenticStepMemory(params) {
+    const { history, coeffs, contextShift, agentWeights, referencedIds, protectedIds, outgoingRole } = params;
+    const tokens = estimateMessagesTokens(history);
+    const budget = calculateCreditBudget(tokens, coeffs.contextMax, coeffs.cMax);
+    const activeTurnId = outgoingRole ? findActiveTurnAnchorId(history) : null;
+    const activeIds = new Set(collectScorableMessageIds(history));
+    const updatedScores = history.map((m) => {
+        if (!isConversationalMessage(m))
+            return m;
+        if (protectedIds.has(m.id)) {
+            return { ...m, forgetScore: 0.0, decayApplied: 0 };
+        }
+        if (activeTurnId && m.id === activeTurnId) {
+            return { ...m, decayApplied: 0 };
+        }
+        if (referencedIds.includes(m.id)) {
+            return {
+                ...m,
+                decayApplied: -(m.forgetScore ?? 0.0),
+                forgetScore: 0.0,
+                turnsAtLimit: 0,
+            };
+        }
+        // Otherwise, keep the message as is (keeps its decayApplied computed at the start of the turn)
+        return m;
+    });
+    const filteredAgentWeights = { ...agentWeights };
+    if (activeTurnId && filteredAgentWeights[activeTurnId]) {
+        delete filteredAgentWeights[activeTurnId];
+    }
+    const creditResolution = resolveTurnCredits({
+        contextShift,
+        agentWeights: filteredAgentWeights,
+        referencedIds,
+        budget,
+        activeIds,
+        activeTurnId,
+    });
+    const scaledAllocation = { ...creditResolution.scaledAllocation };
+    const creditsConsumed = Object.values(scaledAllocation).reduce((sum, n) => sum + n, 0);
+    const credited = validateAndApplyCredits(scaledAllocation, updatedScores).map((m) => ({
+        ...m,
+        creditsAllocated: scaledAllocation[m.id]
+            ? Math.round(scaledAllocation[m.id])
+            : 0,
+    }));
+    const snapshot = buildTurnMemorySnapshot({
+        turnBudget: budget,
+        contextShift,
+        creditsConsumed,
+        agentAllocation: creditResolution.agentAllocation,
+        effectiveAllocation: creditResolution.effectiveAllocation,
+        usedFallback: creditResolution.usedFallback,
+        scaledAllocation,
+        scale: creditResolution.scale,
+        totalRequested: creditResolution.totalRequested,
+        referencedIds,
+        messages: credited,
+        estimateTokens: estimateTextTokens,
+        invalidAgentIds: creditResolution.invalidAgentIds,
+    });
+    return {
+        history: credited,
+        budget,
+        creditsConsumed,
+        scaledAllocation,
+        snapshot,
+        tokens,
+    };
+}
+export function getPressureRatio(tokens, contextMax) {
+    return tokens / contextMax;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// LFS v4.6 — Zero-Configuration Dynamic Watermarking Engine
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * UI-only suggestion for memory cap slider (does not override user profile at execution).
+ *
+ * Formula:
+ *   contextMax ≤ 16,384  →  0.40
+ *   otherwise             →  min(0.40 + log10(contextMax / 10_000) × 0.15, 0.75)
+ *
+ * Effective ranges:
+ *   10k  → 0.40
+ *   1M   → 0.70
+ *   10M+ → 0.75 (ceiling)
+ */
+export function suggestMemoryCapFraction(contextMax) {
+    if (contextMax <= 16384)
+        return 0.40;
+    return Math.min(0.40 + Math.log10(contextMax / 10_000) * 0.15, 0.75);
+}
+/** @deprecated Use suggestMemoryCapFraction for UI hints; use resolveLfsRuntimeConfig for execution. */
+export function calculateCapacityFactor(contextMax) {
+    return suggestMemoryCapFraction(contextMax);
+}
+/**
+ * Returns the effective token cap for the given context window and cap fraction.
+ */
+export function calculateTargetMemoryCap(contextMax, memoryCapFraction) {
+    const fraction = memoryCapFraction ?? suggestMemoryCapFraction(contextMax);
+    return Math.floor(contextMax * fraction);
+}
+/**
+ * Normalised pressure against the memory cap (0.0 → ∞).
+ */
+export function getNormalizedPressure(activeTokens, contextMax, memoryCapFraction) {
+    const cap = calculateTargetMemoryCap(contextMax, memoryCapFraction);
+    return activeTokens / Math.max(1, cap);
+}
+/**
+ * Credit budget with logarithmic floor — guarantees ≥ 10 credits even under
+ * severe context pressure, preventing the agent from going completely silent.
+ *
+ * Formula:
+ *   pressure < 1.0  →  100
+ *   otherwise        →  max(⌊100 / (1 + ln(pressure))⌋, 10)
+ *
+ * Uses the auto-derived cap when called without a hardBufferCap override.
+ */
+export function calculateCreditBudgetV2(activeTokens, contextMax, hardBufferCapOverride) {
+    const cap = hardBufferCapOverride != null
+        ? contextMax * hardBufferCapOverride
+        : calculateTargetMemoryCap(contextMax);
+    const pressure = activeTokens / cap;
+    if (pressure < 1.0)
+        return 100;
+    return Math.max(Math.floor(100 / (1 + Math.log(pressure))), 10);
+}