@atlaskit/editor-plugin-autocomplete 8.0.0 → 9.1.0

package/src/pm-plugins/autocomplete-plugin.ts

@@ -14,7 +14,12 @@ import type { EditorView } from '@atlaskit/editor-prosemirror/view';
 
 import type { AutocompletePlugin } from '../autocompletePluginType';
 
-import { isAutocompleteDebugEnabled } from './debug-mode';
+import {
+	CTC_STYLES,
+	ctcTag,
+	isAutocompleteDebugEnabled,
+	isAutocompleteDebugVerbose,
+} from './debug-mode';
 import { createGhostTextDecorationSet } from './ghost-text-decoration';
 import {
 	createLocalSlowLaneClient,
@@ -23,18 +28,29 @@ import {
 	type LocalSlowLaneLoadSuccess,
 } from './local-slow-lane-client';
 import { loadGrammarDataAsync } from './scoring-pipeline';
-import { createSlowLaneClient, setDefaultSlowLaneClient, isWordBoundary } from './slow-lane-client';
+import {
+	clearDefaultSlowLaneClient,
+	createSlowLaneClient,
+	getDefaultSlowLaneClientStatus,
+	isWordBoundary,
+	setDefaultSlowLaneClient,
+	type SlowLaneClientKind,
+} from './slow-lane-client';
 import {
 	predict,
+	type PredictionResult,
 	loadDefaultVocabulary,
 	loadVectorsAsync,
 	incrementSessionFreq,
 	ingestDocumentPage,
+	getLastPredictionDebug,
+	noteSuggestionAccepted,
 } from './text-predictor';
 
 export const autocompletePluginKey: PluginKey = new PluginKey('autocomplete');
 
-const DEBOUNCE_MS = 150;
+const PREDICTION_COALESCE_MS = 0;
+const GHOST_DECISION_BUDGET_MS = 100;
 const NETWORK_SLOW_LANE_DEBOUNCE_MS = 300;
 const LOCAL_SLOW_LANE_DEBOUNCE_MS = 100;
 const CONTEXT_REFRESH_THROTTLE_MS = 1000;
@@ -49,16 +65,70 @@ const MAX_INGESTED_CONTEXT_TEXTS = 50;
 // on every word boundary for the plugin's lifetime.
 const MAX_CONTEXT_REFRESH_ATTEMPTS = 5;
 const INLINE_LEAF_TEXT = ' ';
+let slowLaneClientInstanceSequence = 0;
 
-// eslint-disable-next-line require-unicode-regexp
-const TRAILING_NON_BOUNDARY_TOKEN_REGEX = /([^\s.,;:!?]*)$/;
 // eslint-disable-next-line require-unicode-regexp
 const WORD_BOUNDARY_CHARS_REGEX = /[\s.,;:!?]/;
+const TRAILING_SURFACE_PREFIX_REGEX = /[\p{L}\p{N}_'-]+$/u;
+
+type AsyncPredictionSignal = {
+	contextKey?: string;
+	familyKey?: string;
+	kind: 'boundary' | 'semantic' | 'surface';
+	latencyMs?: number;
+};
+
+type PredictionDecision = {
+	asyncSignals: number;
+	deadlineAt: number;
+	evaluations: number;
+	position: number;
+	revision: number;
+	startedAt: number;
+	textBefore: string;
+};
 
 const hasDestroy = (
 	client: ReturnType<typeof createSlowLaneClient> | LocalSlowLaneClient,
 ): client is LocalSlowLaneClient => 'destroy' in client && typeof client.destroy === 'function';
 
+export interface CommittedSuggestion {
+	/** Wall-clock latency from the triggering editor update to the committed ghost. */
+	decisionLatencyMs: number;
+	/** Evidence tier that authorized this suggestion for display. */
+	evidenceTier: PredictionResult['evidenceTier'];
+	/** Ghost tail actually rendered and inserted. */
+	ghostText: string;
+	/**
+	 * Mean per-token log-probability of the verified prefix, carried so an
+	 * acceptance can be attributed to the evidence that authorized the display
+	 * rather than to whatever the scorer holds by the time Tab arrives.
+	 */
+	meanTokenLogProbability: number;
+	/**
+	 * Whether a longer candidate in the same pool extended this surface, which
+	 * hands it that pool's mass undivided under the chain rule and puts it near
+	 * the top of the posterior range for a structural reason.
+	 */
+	poolHeldExtension: boolean;
+	/** ProseMirror position at which the ghost is anchored. */
+	position: number;
+	/** Share of its shortlist's mass the model put on this surface. */
+	posterior: number;
+	/** Final confidence-v2 ranking score. */
+	rankScore: number;
+	/** Monotonic editor decision revision that owns this suggestion. */
+	revision: number;
+	/** How many scored candidates this surface's normaliser divided between. */
+	shortlistSize: number;
+	/** Full candidate surface, used by analytics and cooldown. */
+	surface: string;
+	/** Whether the surface is a single word, a bigram, or a phrase. */
+	termType: PredictionResult['termType'];
+	/** Difference between the selected rank score and its closest eligible rival. */
+	winnerMargin: number;
+}
+
 export interface AutocompletePluginState {
 	/** The decoration set containing the ghost text widget */
 	decorationSet: DecorationSet;
@@ -66,14 +136,77 @@ export interface AutocompletePluginState {
 	ghostPosition: number;
 	/** The predicted ghost text to display */
 	ghostText: string;
+	/** Single authoritative snapshot for rendering, insertion, analytics, and cooldown. */
+	suggestion: CommittedSuggestion | null;
 }
 
 const createInitialState = (): AutocompletePluginState => ({
 	ghostText: '',
 	ghostPosition: -1,
 	decorationSet: DecorationSet.empty,
+	suggestion: null,
+});
+
+const clearGhostState = (pluginState: AutocompletePluginState): AutocompletePluginState => ({
+	...pluginState,
+	ghostText: '',
+	ghostPosition: -1,
+	decorationSet: DecorationSet.empty,
+	suggestion: null,
 });
 
+/**
+ * Keep a displayed ghost alive when the user types the character it already
+ * predicted.
+ *
+ * Clearing on every document change throws away a suggestion the keystroke just
+ * confirmed, and the replacement decision has to re-earn it from an empty state
+ * inside the budget — which it often misses, so the ghost blinks out mid-word.
+ * It is worse for multi-word surfaces: typing the space in `machine learning`
+ * empties the current word, and the display gate refuses to show anything again
+ * until three characters of `learning` exist.
+ *
+ * A confirming keystroke is not new information about the prediction, so the
+ * ghost simply advances by one character and the still-running decision is free
+ * to replace it with something better. Anything else — a different character,
+ * a paste, a deletion, an edit elsewhere — clears as before.
+ */
+const advanceGhostThroughTypedCharacter = (
+	tr: ReadonlyTransaction,
+	pluginState: AutocompletePluginState,
+): AutocompletePluginState | null => {
+	const { ghostPosition, ghostText, suggestion } = pluginState;
+	if (ghostText.length < 2 || ghostPosition < 0 || !suggestion) {
+		// A one-character tail leaves nothing to show after advancing.
+		return null;
+	}
+
+	// Exactly one character longer, with the cursor sitting just past the ghost
+	// anchor: together these identify a single insertion made at the anchor
+	// rather than a paste or an edit elsewhere in the document.
+	if (tr.doc.content.size - tr.before.content.size !== 1) {
+		return null;
+	}
+	if (!tr.selection.empty || tr.selection.from !== ghostPosition + 1) {
+		return null;
+	}
+	if (tr.doc.textBetween(ghostPosition, ghostPosition + 1) !== ghostText[0]) {
+		return null;
+	}
+
+	const remaining = ghostText.slice(1);
+	const nextPosition = ghostPosition + 1;
+	return {
+		...pluginState,
+		ghostText: remaining,
+		ghostPosition: nextPosition,
+		decorationSet: createGhostTextDecorationSet(tr.doc, nextPosition, remaining),
+		// `surface` stays the full candidate so cooldown and analytics still
+		// describe the suggestion that was originally committed.
+		suggestion: { ...suggestion, ghostText: remaining, position: nextPosition },
+	};
+};
+
 /**
  * Extract text content before the cursor from the current document.
  * Returns the last ~200 characters for context.
@@ -111,6 +244,9 @@ const getTextBeforeCursor = (state: EditorState): string => {
 	return fullText.slice(-maxChars);
 };
 
+const getTrailingSurfacePrefixLength = (text: string): number =>
+	text.trimEnd().match(TRAILING_SURFACE_PREFIX_REGEX)?.[0].length ?? 0;
+
 /**
  * Set the autocomplete state via a transaction metadata.
  */
@@ -126,18 +262,42 @@ const setAutocompleteMeta = (
  */
 let lastShownGhostText = '';
 
-const showGhostText = (view: EditorView, text: string, position: number): void => {
+const showGhostText = (
+	view: EditorView,
+	prediction: PredictionResult,
+	position: number,
+	revision: number,
+	decisionStartedAt: number,
+): CommittedSuggestion | null => {
 	try {
 		const { state, dispatch } = view;
-		const decorationSet = createGhostTextDecorationSet(state, position, text);
+		const suggestion: CommittedSuggestion = {
+			decisionLatencyMs: performance.now() - decisionStartedAt,
+			evidenceTier: prediction.evidenceTier,
+			ghostText: prediction.text,
+			meanTokenLogProbability: prediction.meanTokenLogProbability,
+			poolHeldExtension: prediction.poolHeldExtension,
+			position,
+			posterior: prediction.posterior,
+			rankScore: prediction.rankScore,
+			revision,
+			shortlistSize: prediction.shortlistSize,
+			surface: prediction.surface,
+			termType: prediction.termType,
+			winnerMargin: prediction.winnerMargin,
+		};
+		const decorationSet = createGhostTextDecorationSet(state.doc, position, prediction.text);
 		const tr = setAutocompleteMeta(state.tr, {
-			ghostText: text,
+			ghostText: prediction.text,
 			ghostPosition: position,
 			decorationSet,
+			suggestion,
 		});
 		dispatch(tr);
+		return suggestion;
 	} catch (error) {
 		logException(error as Error, { location: 'editor-plugin-autocomplete/showGhostText' });
+		return null;
 	}
 };
 
@@ -156,6 +316,7 @@ const clearGhostText = (state: EditorState, dispatch?: (tr: Transaction) => void
 				ghostText: '',
 				ghostPosition: -1,
 				decorationSet: DecorationSet.empty,
+				suggestion: null,
 			});
 			dispatch(tr);
 		} catch (error) {
@@ -169,42 +330,48 @@ const clearGhostText = (state: EditorState, dispatch?: (tr: Transaction) => void
 /**
  * Accept the current ghost text suggestion and insert it into the document.
  */
-const acceptGhostText = (state: EditorState, dispatch?: (tr: Transaction) => void): boolean => {
+const acceptGhostText = (
+	state: EditorState,
+	dispatch?: (tr: Transaction) => void,
+): CommittedSuggestion | null => {
 	const pluginState = autocompletePluginKey.getState(state) as AutocompletePluginState | undefined;
-	if (!pluginState || !pluginState.ghostText) {
-		return false;
+	if (!pluginState?.suggestion || !pluginState.ghostText) {
+		return null;
 	}
 
 	if (dispatch) {
 		try {
-			const { ghostText, ghostPosition } = pluginState;
+			const { ghostText, ghostPosition, suggestion } = pluginState;
 			let tr = state.tr.insertText(ghostText, ghostPosition);
 			tr = setAutocompleteMeta(tr, {
 				ghostText: '',
 				ghostPosition: -1,
 				decorationSet: DecorationSet.empty,
+				suggestion: null,
 			});
 			dispatch(tr);
+			return suggestion;
 		} catch (error) {
 			logException(error as Error, { location: 'editor-plugin-autocomplete/acceptGhostText' });
-			return false;
+			return null;
 		}
 	}
-	return true;
+	return pluginState.suggestion;
 };
 
 const acceptGhostTextWithAnalytics = (
 	state: EditorState,
 	dispatch: ((tr: Transaction) => void) | undefined,
-	onAccepted: (ghostText: string) => void,
+	onAccepted: (suggestion: CommittedSuggestion) => void,
 ): boolean => {
-	const pluginState = autocompletePluginKey.getState(state) as AutocompletePluginState | undefined;
-	const ghostText = pluginState?.ghostText ?? '';
-	const accepted = acceptGhostText(state, dispatch);
-	if (accepted) {
-		onAccepted(ghostText);
+	const acceptedSuggestion = acceptGhostText(state, dispatch);
+	if (acceptedSuggestion) {
+		// Start the post-accept cooldown so the just-accepted unit isn't immediately
+		// re-offered (QI-2 echo, e.g. `end to end` → `end to end to end`).
+		noteSuggestionAccepted(acceptedSuggestion.surface);
+		onAccepted(acceptedSuggestion);
 	}
-	return accepted;
+	return acceptedSuggestion !== null;
 };
 
 /**
@@ -323,15 +490,6 @@ const getLeadingTextCharacter = (text?: string): string | undefined => {
 	return String.fromCodePoint(firstCodePoint);
 };
 
-const getTypedLengthForPrediction = (textBefore: string): number => {
-	if (isWordBoundary(textBefore)) {
-		return 0;
-	}
-
-	const trailingToken = textBefore.match(TRAILING_NON_BOUNDARY_TOKEN_REGEX)?.[1] ?? '';
-	return trailingToken.length;
-};
-
 const isEnglishLocale = (locale?: string): boolean => {
 	if (!locale) {
 		return false;
@@ -350,6 +508,7 @@ export const createAutocompletePlugin = (
 	const isAutocompleteEnabled = isEnglishLocale(locale);
 
 	let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+	let decisionDeadlineTimer: ReturnType<typeof setTimeout> | null = null;
 	let hasIngestedPage = false;
 	let resolvedContext: AutocompleteContext | undefined;
 	/**
@@ -359,6 +518,10 @@ export const createAutocompletePlugin = (
 	 */
 	let currentView: EditorView | null = null;
 	let unsubscribeFromContextUpdates: (() => void) | undefined;
+	// "Prime, don't ask-and-read": semantic, Tier-A, and Tier-B results land
+	// asynchronously, often with no following keystroke. Re-run prediction when
+	// they arrive so the caches are consumed immediately.
+	let reschedulePredictionOnSlowLaneResult: ((signal: AsyncPredictionSignal) => void) | null = null;
 	/**
 	 * Set after accepting a suggestion so the next doc-change update
 	 * skips scheduling a new prediction for the just-inserted text.
@@ -372,8 +535,8 @@ export const createAutocompletePlugin = (
 	 * re-showing the same suggestion. Resets to null as soon as the text changes.
 	 */
 	let dismissedContext: string | null = null;
-	let lastSuggestionTypedLength = 0;
-	let lastSuggestionLength = 0;
+	let decisionRevision = 0;
+	let activeDecision: PredictionDecision | undefined;
 
 	/**
 	 * cold  → no slow-lane vector received yet; frequency-only trie scoring
@@ -435,9 +598,9 @@ export const createAutocompletePlugin = (
 		});
 	};
 
-	const fireSuggestionInsertedAnalytics = (ghostText: string): void => {
-		const typedLength = lastSuggestionTypedLength;
-		const suggestionLength = lastSuggestionLength || typedLength + ghostText.length;
+	const fireSuggestionInsertedAnalytics = (suggestion: CommittedSuggestion): void => {
+		const typedLength = Math.max(0, suggestion.surface.length - suggestion.ghostText.length);
+		const suggestionLength = suggestion.surface.length;
 		const kssDelta = suggestionLength - typedLength;
 
 		api?.analytics?.actions.fireAnalyticsEvent({
@@ -459,14 +622,44 @@ export const createAutocompletePlugin = (
 				debounceMs: LOCAL_SLOW_LANE_DEBOUNCE_MS,
 				onLoadSuccess: fireLocalModelLoadedAnalytics,
 				onLoadError: fireLocalModelLoadFailedAnalytics,
+				// Re-run prediction for each independently scheduled model result.
+				onUpdate: () => reschedulePredictionOnSlowLaneResult?.({ kind: 'semantic' }),
+				onBoundaryLmUpdate: ({ contextKey, familyKey, latencyMs }) =>
+					reschedulePredictionOnSlowLaneResult?.({
+						contextKey,
+						familyKey,
+						kind: 'boundary',
+						latencyMs,
+					}),
+				onSurfaceScoreUpdate: ({ contextKey, familyKey, latencyMs }) =>
+					reschedulePredictionOnSlowLaneResult?.({
+						contextKey,
+						familyKey,
+						kind: 'surface',
+						latencyMs,
+					}),
 				surface,
 			})
 		: createSlowLaneClient({
 				baseUrl: '',
 				debounceMs: NETWORK_SLOW_LANE_DEBOUNCE_MS,
+				// Re-run prediction when the BE semantic vector / LM logits land so
+				// warm-mode unigram ranking applies without waiting for a keystroke.
+				onUpdate: () => reschedulePredictionOnSlowLaneResult?.({ kind: 'semantic' }),
 				surface,
 			});
-	setDefaultSlowLaneClient(slowLaneClient);
+	const slowLaneClientKind: SlowLaneClientKind = options?.useLocalModel ? 'localLlm' : 'server';
+	const slowLaneClientId = `${surface}:${slowLaneClientKind}:${++slowLaneClientInstanceSequence}`;
+	setDefaultSlowLaneClient(slowLaneClient, {
+		clientId: slowLaneClientId,
+		kind: slowLaneClientKind,
+	});
+	const registeredSlowLaneStatus = getDefaultSlowLaneClientStatus();
+	ctcTag(
+		'init',
+		`slow lane registered · id=${slowLaneClientId} · selected=${slowLaneClientKind} · canonical=${registeredSlowLaneStatus.canonicalScoringSupported ? 'yes' : 'no'} · ready=${registeredSlowLaneStatus.localModelReady ?? 'n/a'}`,
+		slowLaneClientKind === 'localLlm' ? CTC_STYLES.good : CTC_STYLES.warn,
+	);
 
 	let contextRequestInFlight = false;
 	let lastContextRefreshAt = 0;
@@ -476,7 +669,67 @@ export const createAutocompletePlugin = (
 	// Set when the plugin is torn down so in-flight getContext() resolutions don't
 	// mutate the global text-predictor state after destruction.
 	let destroyed = false;
-	const ingestedContextTexts = new Set<string>();
+	// L1 ingestion cannot run before the vocabulary has loaded: `incrementSessionFreq`
+	// only touches trie nodes that already exist, so an empty trie silently rejects
+	// every word. Text that arrives first — which a page usually does, since the
+	// chat resolves it on focus in the same tick as the load starts — is held here
+	// and applied once the load has settled.
+	const pendingSessionContextTexts = new Set<string>();
+	const sessionIngestedContextTexts = new Set<string>();
+	let isVocabularyReady = false;
+	let vocabularyLoadPromise: Promise<void> | undefined;
+
+	const addBoundedContextText = (texts: Set<string>, text: string): void => {
+		texts.add(text);
+		// Evict oldest entries (Set preserves insertion order) to bound memory.
+		while (texts.size > MAX_INGESTED_CONTEXT_TEXTS) {
+			const oldest = texts.values().next().value;
+			if (oldest === undefined) {
+				break;
+			}
+			texts.delete(oldest);
+		}
+	};
+
+	const flushPendingSessionContext = (): void => {
+		if (!isVocabularyReady || destroyed) {
+			return;
+		}
+		for (const text of pendingSessionContextTexts) {
+			if (!sessionIngestedContextTexts.has(text)) {
+				ingestDocumentPage(text);
+				addBoundedContextText(sessionIngestedContextTexts, text);
+			}
+			pendingSessionContextTexts.delete(text);
+		}
+	};
+
+	const ensureVocabularyReady = (): Promise<void> => {
+		if (isVocabularyReady) {
+			flushPendingSessionContext();
+			return Promise.resolve();
+		}
+		vocabularyLoadPromise ??= loadDefaultVocabulary({
+			isLocalLLM: options?.useLocalModel ?? false,
+			surface,
+		})
+			.then(() => {
+				if (destroyed) {
+					return;
+				}
+				isVocabularyReady = true;
+				flushPendingSessionContext();
+			})
+			.catch((error) => {
+				// Do not consume the pending text on failure. A later focus retries the
+				// load and can still apply the original context exactly once.
+				vocabularyLoadPromise = undefined;
+				logException(error as Error, {
+					location: 'editor-plugin-autocomplete/loadDefaultVocabulary',
+				});
+			});
+		return vocabularyLoadPromise;
+	};
 
 	const logContextResolved = (source: string, context?: AutocompleteContext): void => {
 		if (!isAutocompleteDebugEnabled()) {
@@ -484,18 +737,13 @@ export const createAutocompletePlugin = (
 		}
 
 		// eslint-disable-next-line no-console
-		console.log(
-			'%c[Autocomplete] %cgetContext resolved',
-			'color: #00b8d9; font-weight: bold;',
-			'color: inherit;',
-			{
-				source,
-				hasParentComment: !!context?.parentCommentContent,
-				parentCommentPreview: context?.parentCommentContent?.slice(0, 80),
-				siblingCount: context?.siblingCommentsContents?.length ?? 0,
-				hasFullPage: !!context?.fullPageContent,
-			},
-		);
+		console.log('%c[CTC:signal]%c getContext resolved', CTC_STYLES.brand, CTC_STYLES.body, {
+			source,
+			hasParentComment: !!context?.parentCommentContent,
+			parentCommentPreview: context?.parentCommentContent?.slice(0, 80),
+			siblingCount: context?.siblingCommentsContents?.length ?? 0,
+			hasFullPage: !!context?.fullPageContent,
+		});
 	};
 
 	const applyContext = (context: AutocompleteContext): void => {
@@ -510,20 +758,11 @@ export const createAutocompletePlugin = (
 		resolvedContext = { ...resolvedContext, ...definedContext };
 
 		const ingestContextText = (text?: string): void => {
-			if (!text || ingestedContextTexts.has(text)) {
+			if (!text || sessionIngestedContextTexts.has(text)) {
 				return;
 			}
 
-			ingestedContextTexts.add(text);
-			// Evict oldest entries (Set preserves insertion order) to bound memory.
-			while (ingestedContextTexts.size > MAX_INGESTED_CONTEXT_TEXTS) {
-				const oldest = ingestedContextTexts.values().next().value;
-				if (oldest === undefined) {
-					break;
-				}
-				ingestedContextTexts.delete(oldest);
-			}
-			ingestDocumentPage(text);
+			addBoundedContextText(pendingSessionContextTexts, text);
 		};
 
 		ingestContextText(context.fullPageContent);
@@ -531,6 +770,7 @@ export const createAutocompletePlugin = (
 		for (const siblingCommentContent of context.siblingCommentsContents ?? []) {
 			ingestContextText(siblingCommentContent);
 		}
+		flushPendingSessionContext();
 
 		// Context arrived after word boundaries may already have fired. Re-send
 		// slow-lane context immediately so the next inference includes the thread.
@@ -593,77 +833,273 @@ export const createAutocompletePlugin = (
 		return true;
 	};
 
-	/**
-	 * Schedule a prediction after a short debounce.
-	 * Tier 1 predictions are synchronous (<0.1ms) but we still debounce
-	 * to avoid unnecessary work on rapid keystrokes.
-	 */
-	const schedulePrediction = (view: EditorView): void => {
+	const clearDecisionTimers = (): void => {
 		if (debounceTimer) {
 			clearTimeout(debounceTimer);
+			debounceTimer = null;
 		}
+		if (decisionDeadlineTimer) {
+			clearTimeout(decisionDeadlineTimer);
+			decisionDeadlineTimer = null;
+		}
+	};
 
-		debounceTimer = setTimeout(() => {
-			try {
-				const { state } = view;
-				const { selection } = state;
+	const cancelActiveDecision = (): void => {
+		clearDecisionTimers();
+		activeDecision = undefined;
+	};
 
-				if (!selection.empty) {
-					return;
-				}
+	const isDecisionSnapshotCurrent = (view: EditorView, decision: PredictionDecision): boolean => {
+		const { state } = view;
+		return (
+			state.selection.empty &&
+			state.selection.from === decision.position &&
+			getTextBeforeCursor(state) === decision.textBefore
+		);
+	};
 
-				// Suppress suggestions when the cursor is mid-word — only offer
-				// completions when the cursor is at the trailing edge of a token.
-				// nodeAfter correctly handles inline atoms (mentions, emojis) where
-				// parentOffset and textContent indices diverge.
-				const nodeAfter = selection.$from.nodeAfter;
-				const charAfterCursor = nodeAfter?.isText
-					? getLeadingTextCharacter(nodeAfter.text)
-					: undefined;
-				// Only suppress for Unicode letters, digits, and underscore — hyphens,
-				// apostrophes, and similar punctuation are valid left-edge boundaries
-				// and should not block suggestions (e.g. cursor before '-' in compound-word).
-				if (charAfterCursor && isMidWordCharacter(charAfterCursor)) {
-					return;
-				}
+	const isDecisionCurrent = (view: EditorView, decision: PredictionDecision): boolean =>
+		activeDecision?.revision === decision.revision && isDecisionSnapshotCurrent(view, decision);
 
-				const textBefore = getTextBeforeCursor(state);
+	const expireActiveDecision = (decision: PredictionDecision): void => {
+		if (activeDecision?.revision !== decision.revision) {
+			return;
+		}
 
-				// Suppress re-showing the same suggestion the user just dismissed.
-				// Once the text context changes (user types or deletes), this clears automatically.
-				if (textBefore === dismissedContext) {
-					return;
-				}
-				dismissedContext = null;
+		cancelActiveDecision();
+	};
 
-				if (textBefore.trim().length < 3) {
-					return;
-				}
+	const evaluateActiveDecision = (view: EditorView, revision: number): void => {
+		const decision = activeDecision;
+		if (!decision || decision.revision !== revision || !isDecisionCurrent(view, decision)) {
+			return;
+		}
 
-				const prediction = predict(textBefore);
-
-				if (prediction && prediction.length > 0) {
-					const typedLength = getTypedLengthForPrediction(textBefore);
-					lastSuggestionTypedLength = typedLength;
-					lastSuggestionLength = typedLength + prediction.length;
-
-					showGhostText(view, prediction, selection.from);
-					if (prediction !== lastShownGhostText) {
-						lastShownGhostText = prediction;
-						api?.analytics?.actions.fireAnalyticsEvent({
-							action: ACTION.SUGGESTION_VIEWED,
-							actionSubject: ACTION_SUBJECT.CONTEXTUAL_TYPEAHEAD,
-							eventType: EVENT_TYPE.TRACK,
-							attributes: { completionSource: getCompletionSource(), surface },
-						});
-					}
+		if (performance.now() > decision.deadlineAt) {
+			expireActiveDecision(decision);
+			return;
+		}
+		decision.evaluations++;
+
+		try {
+			const { state } = view;
+			const { selection } = state;
+
+			// Suppress suggestions when the cursor is mid-word — only offer
+			// completions when the cursor is at the trailing edge of a token.
+			const nodeAfter = selection.$from.nodeAfter;
+			const charAfterCursor = nodeAfter?.isText
+				? getLeadingTextCharacter(nodeAfter.text)
+				: undefined;
+			if (charAfterCursor && isMidWordCharacter(charAfterCursor)) {
+				cancelActiveDecision();
+				return;
+			}
+
+			if (decision.textBefore === dismissedContext) {
+				cancelActiveDecision();
+				return;
+			}
+			dismissedContext = null;
+
+			// Two characters are enough to prefetch the canonical shortlist. The
+			// predictor itself withholds display until the three-character gate.
+			if (decision.textBefore.trim().length < 2) {
+				cancelActiveDecision();
+				return;
+			}
+
+			const prediction = predict(decision.textBefore);
+			if (!prediction || prediction.text.length === 0) {
+				// Remain in `collecting` until an async signal arrives or the hard
+				// deadline expires. We never display a provisional fallback.
+				return;
+			}
+
+			const readyAtMs = performance.now() - decision.startedAt;
+			if (readyAtMs > GHOST_DECISION_BUDGET_MS) {
+				cancelActiveDecision();
+				if (isAutocompleteDebugEnabled()) {
+					// eslint-disable-next-line no-console
+					console.log(
+						'%c[CTC:budget]%c fully gated after render deadline (render suppressed)',
+						CTC_STYLES.section,
+						CTC_STYLES.body,
+						{
+							revision: decision.revision,
+							readyAtMs,
+							surface: prediction.surface,
+						},
+					);
 				}
-			} catch (error) {
-				logException(error as Error, {
-					location: 'editor-plugin-autocomplete/schedulePrediction',
+				return;
+			}
+
+			const suggestion = showGhostText(
+				view,
+				prediction,
+				decision.position,
+				decision.revision,
+				decision.startedAt,
+			);
+			if (!suggestion) {
+				cancelActiveDecision();
+				return;
+			}
+
+			cancelActiveDecision();
+			if (isAutocompleteDebugEnabled()) {
+				// eslint-disable-next-line no-console
+				console.log(
+					'%c[CTC:decision]%c committed immutable ghost',
+					CTC_STYLES.brand,
+					CTC_STYLES.body,
+					{
+						revision: suggestion.revision,
+						surface: suggestion.surface,
+						ghostText: suggestion.ghostText,
+						evidenceTier: suggestion.evidenceTier,
+						rankScore: suggestion.rankScore,
+						winnerMargin: suggestion.winnerMargin,
+						decisionLatencyMs: suggestion.decisionLatencyMs,
+						budgetMs: GHOST_DECISION_BUDGET_MS,
+						typedPrefixLength: getTrailingSurfacePrefixLength(decision.textBefore),
+						evaluations: decision.evaluations,
+						asyncSignals: decision.asyncSignals,
+						readyWithinBudget: suggestion.decisionLatencyMs <= GHOST_DECISION_BUDGET_MS,
+					},
+				);
+			}
+			if (suggestion.ghostText !== lastShownGhostText) {
+				lastShownGhostText = suggestion.ghostText;
+				api?.analytics?.actions.fireAnalyticsEvent({
+					action: ACTION.SUGGESTION_VIEWED,
+					actionSubject: ACTION_SUBJECT.CONTEXTUAL_TYPEAHEAD,
+					eventType: EVENT_TYPE.TRACK,
+					attributes: { completionSource: getCompletionSource(), surface },
 				});
 			}
-		}, DEBOUNCE_MS);
+		} catch (error) {
+			cancelActiveDecision();
+			logException(error as Error, {
+				location: 'editor-plugin-autocomplete/evaluateActiveDecision',
+			});
+		}
+	};
+
+	const beginPredictionDecision = (view: EditorView): void => {
+		cancelActiveDecision();
+		const { state } = view;
+		if (!state.selection.empty) {
+			return;
+		}
+
+		const startedAt = performance.now();
+		const textBefore = getTextBeforeCursor(state);
+		const revision = ++decisionRevision;
+		activeDecision = {
+			asyncSignals: 0,
+			deadlineAt: startedAt + GHOST_DECISION_BUDGET_MS,
+			evaluations: 0,
+			position: state.selection.from,
+			revision,
+			startedAt,
+			textBefore,
+		};
+		if (isAutocompleteDebugEnabled()) {
+			// eslint-disable-next-line no-console
+			console.log('%c[CTC:decision]%c collecting', CTC_STYLES.brand, CTC_STYLES.body, {
+				revision,
+				budgetMs: GHOST_DECISION_BUDGET_MS,
+				coalesceMs: PREDICTION_COALESCE_MS,
+				typedPrefixLength: getTrailingSurfacePrefixLength(activeDecision.textBefore),
+				textBefore: activeDecision.textBefore.slice(-80),
+			});
+		}
+
+		debounceTimer = setTimeout(() => {
+			debounceTimer = null;
+			evaluateActiveDecision(view, revision);
+		}, PREDICTION_COALESCE_MS);
+		decisionDeadlineTimer = setTimeout(() => {
+			decisionDeadlineTimer = null;
+			if (activeDecision?.revision === revision) {
+				const expiredDecision = activeDecision;
+				if (isAutocompleteDebugEnabled()) {
+					const elapsedMs = performance.now() - expiredDecision.startedAt;
+					const predictionDebug = getLastPredictionDebug();
+					const matchingPredictionDebug =
+						predictionDebug?.textBefore === expiredDecision.textBefore ? predictionDebug : null;
+					const abstentionPrefix = '— abstain: ';
+					const predictorDecision = matchingPredictionDebug?.decision;
+					const predictorReason = predictorDecision?.startsWith(abstentionPrefix)
+						? predictorDecision.slice(abstentionPrefix.length)
+						: predictorDecision;
+					const decisionMessage =
+						predictorReason && !matchingPredictionDebug?.awaitingAsyncEvidence
+							? `abstain: ${predictorReason}`
+							: `abstain: ${GHOST_DECISION_BUDGET_MS}ms decision budget expired${predictorReason ? ` · ${predictorReason}` : ''}`;
+					// eslint-disable-next-line no-console
+					console.log(`%c[CTC:decision]%c ${decisionMessage}`, CTC_STYLES.brand, CTC_STYLES.body, {
+						revision,
+						budgetMs: GHOST_DECISION_BUDGET_MS,
+						elapsedMs,
+						typedPrefixLength: getTrailingSurfacePrefixLength(expiredDecision.textBefore),
+						evaluations: expiredDecision.evaluations,
+						asyncSignals: expiredDecision.asyncSignals,
+						textBefore: expiredDecision.textBefore.slice(-80),
+						predictorDecision: predictorReason ?? null,
+					});
+				}
+				expireActiveDecision(expiredDecision);
+			}
+		}, GHOST_DECISION_BUDGET_MS);
+	};
+
+	// Async semantic/canonical results may complete the active decision, but they
+	// never create a new decision or replace an already committed ghost.
+	reschedulePredictionOnSlowLaneResult = (signal) => {
+		if (destroyed || !currentView) {
+			return;
+		}
+		if (!activeDecision) {
+			return;
+		}
+		const revision = activeDecision.revision;
+		const elapsedMs = performance.now() - activeDecision.startedAt;
+		const remainingMs = activeDecision.deadlineAt - performance.now();
+		if (remainingMs < 0) {
+			const expiredDecision = activeDecision;
+			expireActiveDecision(expiredDecision);
+			return;
+		}
+
+		activeDecision.asyncSignals++;
+		if (isAutocompleteDebugVerbose()) {
+			// eslint-disable-next-line no-console
+			console.log(
+				'%c[CTC:readiness]%c async evidence signal',
+				CTC_STYLES.section,
+				CTC_STYLES.body,
+				{
+					...signal,
+					revision,
+					elapsedMs,
+					remainingMs: Math.max(0, remainingMs),
+					typedPrefixLength: getTrailingSurfacePrefixLength(activeDecision.textBefore),
+					withinBudget: remainingMs >= 0,
+				},
+			);
+		}
+		if (debounceTimer) {
+			clearTimeout(debounceTimer);
+		}
+		debounceTimer = setTimeout(() => {
+			debounceTimer = null;
+			if (currentView) {
+				evaluateActiveDecision(currentView, revision);
+			}
+		}, 0);
 	};
 
 	const maybeUpdateSessionFrequency = (view: EditorView, prevState: EditorState): void => {
@@ -712,23 +1148,14 @@ export const createAutocompletePlugin = (
 					return { ...pluginState, ...meta };
 				}
 
-				// A new prediction is scheduled from view.update.
+				// A new prediction is scheduled from view.update either way; the
+				// surviving ghost only covers the gap until it commits.
 				if (tr.docChanged) {
-					return {
-						...pluginState,
-						ghostText: '',
-						ghostPosition: -1,
-						decorationSet: DecorationSet.empty,
-					};
+					return advanceGhostThroughTypedCharacter(tr, pluginState) ?? clearGhostState(pluginState);
 				}
 
 				if (tr.selectionSet && pluginState.ghostText) {
-					return {
-						...pluginState,
-						ghostText: '',
-						ghostPosition: -1,
-						decorationSet: DecorationSet.empty,
-					};
+					return clearGhostState(pluginState);
 				}
 
 				return pluginState;
@@ -745,22 +1172,25 @@ export const createAutocompletePlugin = (
 
 			handleKeyDown: keydownHandler({
 				Tab: (state: EditorState, dispatch?: (tr: Transaction) => void) => {
-					return acceptGhostTextWithAnalytics(state, dispatch, (ghostText) => {
+					return acceptGhostTextWithAnalytics(state, dispatch, (suggestion) => {
 						justAccepted = true;
 						lastShownGhostText = '';
-						fireSuggestionInsertedAnalytics(ghostText);
+						cancelActiveDecision();
+						fireSuggestionInsertedAnalytics(suggestion);
 					});
 				},
 				ArrowRight: (state: EditorState, dispatch?: (tr: Transaction) => void) => {
-					return acceptGhostTextWithAnalytics(state, dispatch, (ghostText) => {
+					return acceptGhostTextWithAnalytics(state, dispatch, (suggestion) => {
 						justAccepted = true;
 						lastShownGhostText = '';
-						fireSuggestionInsertedAnalytics(ghostText);
+						cancelActiveDecision();
+						fireSuggestionInsertedAnalytics(suggestion);
 					});
 				},
 				Escape: (state: EditorState, dispatch?: (tr: Transaction) => void) => {
 					const didClear = clearGhostText(state, dispatch);
 					if (didClear) {
+						cancelActiveDecision();
 						dismissedContext = getTextBeforeCursor(state);
 						fireSuggestionDismissedAnalytics('escape');
 					}
@@ -779,6 +1209,7 @@ export const createAutocompletePlugin = (
 						| undefined;
 					if (pluginState?.ghostText) {
 						clearGhostText(view.state, view.dispatch);
+						cancelActiveDecision();
 						fireSuggestionDismissedAnalytics('blur');
 					}
 					return false;
@@ -791,6 +1222,7 @@ export const createAutocompletePlugin = (
 					if (!event.target.closest('[data-autocomplete-ghost="true"]')) {
 						const didClear = clearGhostText(view.state, view.dispatch);
 						if (didClear) {
+							cancelActiveDecision();
 							dismissedContext = getTextBeforeCursor(view.state);
 							lastShownGhostText = '';
 							fireSuggestionDismissedAnalytics('click');
@@ -800,10 +1232,11 @@ export const createAutocompletePlugin = (
 
 					event.preventDefault();
 
-					const accepted = acceptGhostTextWithAnalytics(view.state, view.dispatch, (ghostText) => {
+					const accepted = acceptGhostTextWithAnalytics(view.state, view.dispatch, (suggestion) => {
 						justAccepted = true;
 						lastShownGhostText = '';
-						fireSuggestionInsertedAnalytics(ghostText);
+						cancelActiveDecision();
+						fireSuggestionInsertedAnalytics(suggestion);
 					});
 
 					if (accepted) {
@@ -817,14 +1250,7 @@ export const createAutocompletePlugin = (
 						return false;
 					}
 
-					loadDefaultVocabulary({
-						isLocalLLM: options?.useLocalModel ?? false,
-						surface,
-					}).catch((error) => {
-						logException(error as Error, {
-							location: 'editor-plugin-autocomplete/loadDefaultVocabulary',
-						});
-					});
+					void ensureVocabularyReady();
 					loadVectorsAsync({
 						isLocalLLM: options?.useLocalModel ?? false,
 						surface,
@@ -881,9 +1307,7 @@ export const createAutocompletePlugin = (
 							// the dismissedContext guard and abort until the user types again.
 							dismissedContext = getTextBeforeCursor(view.state);
 
-							if (debounceTimer) {
-								clearTimeout(debounceTimer);
-							}
+							cancelActiveDecision();
 							return;
 						}
 
@@ -914,7 +1338,9 @@ export const createAutocompletePlugin = (
 							}
 						}
 
-						schedulePrediction(view);
+						beginPredictionDecision(view);
+					} else if (!prevState.selection.eq(view.state.selection)) {
+						cancelActiveDecision();
 					}
 				},
 				destroy: () => {
@@ -922,14 +1348,18 @@ export const createAutocompletePlugin = (
 					currentView = null;
 					unsubscribeFromContextUpdates?.();
 					unsubscribeFromContextUpdates = undefined;
-					if (debounceTimer) {
-						clearTimeout(debounceTimer);
-					}
+					cancelActiveDecision();
+					const releasedDefaultClient = clearDefaultSlowLaneClient(slowLaneClient);
+					ctcTag(
+						'init',
+						`slow lane teardown · id=${slowLaneClientId} · default=${releasedDefaultClient ? 'released' : 'retained newer owner'}`,
+						releasedDefaultClient ? CTC_STYLES.dim : CTC_STYLES.warn,
+					);
 					if (hasDestroy(slowLaneClient)) {
 						slowLaneClient.destroy();
 					}
-					ingestedContextTexts.clear();
-					setDefaultSlowLaneClient(null);
+					pendingSessionContextTexts.clear();
+					sessionIngestedContextTexts.clear();
 				},
 			};
 		},