@atlaskit/editor-plugin-autocomplete 8.0.0 → 9.0.0

package/src/pm-plugins/scoring-pipeline.ts

@@ -11,23 +11,41 @@
 import { EXPERIENCE_NAME, failExp, startExp, succeedExp } from '../analytics/ufo';
 
 import { ARTIFACT_NAME, fetchArtifactJson } from './artifacts-manifest';
+import type { CanonicalLmEvidence } from './canonical-lm-scoring';
 import { isAutocompleteDebugEnabled } from './debug-mode';
 
 // ─── Types ──────────────────────────────────────────────────
 
+/**
+ * A completion term is `(term, termType)`. `word` is the v1 default; `bigram`
+ * (2 tokens) and `phrase` (3 tokens) are multi-word units mined by the producer.
+ */
+export type TermType = 'word' | 'bigram' | 'phrase';
+
 export interface ScoringCandidate {
+	/** NPMI-style association strength (bigram/phrase only). */
+	association?: number | null;
 	authorFreq: number;
 	docFreq: number;
+	/** Last-token POS of a multi-word term (bigram/phrase only). */
+	headPos?: string | null;
+	/** Per-token POS sequence of a multi-word term (bigram/phrase only). */
+	posSeq?: string[] | null;
 	sessionFreq: number;
 	tenantFreq: number;
+	/** Defaults to `'word'` when omitted (back-compat with word-only callers). */
+	termType?: TermType;
 	word: string;
 }
 
 export interface ScoredCandidate {
 	finalScore: number;
 	freqScore: number;
+	lmEvidence: CanonicalLmEvidence | null;
 	lmScore: number;
 	semanticScore: number;
+	stage1Score: number;
+	termType: TermType;
 	word: string;
 }
 
@@ -48,14 +66,32 @@ interface GrammarTransitions {
 	transitions: Record<string, PosTransitionRule>;
 }
 
+type PosTagsRecord = Record<string, string[]>;
+
 // ─── Scoring Constants ──────────────────────────────────────
 
 const ALPHA = 0.5;
 const BETA = 0.5;
 const NEUTRAL_SCORE = 0.5;
+// Multiplicative Stage-1 boost applied to a multi-word term proportional to its
+// (clamped [0,1]) NPMI association, so a strongly-collocated phrase outranks a
+// coincidental word sequence of comparable freq/semantics. Tunable.
+const ASSOCIATION_BOOST = 0.5;
 export const STAGE1_WEIGHT = 0.35;
 export const STAGE2_WEIGHT = 0.65;
 export const MIN_STAGE1_SCORE = 0.35;
+/**
+ * How far the leading candidate must sit above the runner-up on the blended
+ * score before a ghost is committed.
+ *
+ * Lives beside the weights it is measured in, because it is only meaningful on
+ * that scale — and because both the arbitration that applies it and the
+ * scheduler that decides when reading more tokens can no longer change the
+ * outcome have to use the same number. When those two drifted apart, the
+ * scheduler stopped early on a margin the arbitration did not recognise and the
+ * abstention that followed was invisible from either side.
+ */
+export const MIN_WINNER_MARGIN = 0.08;
 const L1_SESSION_CAP = 1.2;
 // Minimum prefix-payload max LM probability before Stage 2 activates.
 // Below this threshold the LM signal is too weak to suppress Stage 1 — finalScore
@@ -75,13 +111,36 @@ let posTags: Map<string, string[]> = new Map();
  */
 let ghostPosTags: Record<string, string[]> = {};
 
+let grammarDataPromise: Promise<void> | undefined;
+
 /**
  * Precomputed map from each POS tag to the set of allowed next POS tags, so
  * applyGrammarFilter never re-iterates the transition rules per call.
  */
 let precomputedAllowedByPos: Map<string, Set<string>> = new Map();
 
-let grammarDataPromise: Promise<void> | undefined;
+const isPosTagsRecord = (payload: unknown): payload is PosTagsRecord => {
+	if (payload == null || typeof payload !== 'object') {
+		return false;
+	}
+	return Object.values(payload as Record<string, unknown>).every(
+		(value) => Array.isArray(value) && value.every((entry) => typeof entry === 'string'),
+	);
+};
+
+const isGrammarTransitions = (payload: unknown): payload is GrammarTransitions => {
+	if (payload == null || typeof payload !== 'object') {
+		return false;
+	}
+	const transitions = (payload as { transitions?: unknown }).transitions;
+	if (transitions == null || typeof transitions !== 'object') {
+		return false;
+	}
+	return Object.values(transitions as Record<string, unknown>).every((value) => {
+		const allowed = (value as { allowed?: unknown })?.allowed;
+		return Array.isArray(allowed) && allowed.every((entry) => typeof entry === 'string');
+	});
+};
 
 const setGrammarData = (data: {
 	ghostPosTags: Record<string, string[]>;
@@ -125,20 +184,35 @@ export const loadGrammarDataAsync = (options?: {
 
 		try {
 			const [posTagsData, ghostPosTagsData, grammarTransitionsData] = await Promise.all([
-				fetchArtifactJson<Record<string, string[]>>(ARTIFACT_NAME.POS_TAGS),
-				fetchArtifactJson<Record<string, string[]>>(ARTIFACT_NAME.GHOST_POS_TAGS),
-				fetchArtifactJson<GrammarTransitions>(ARTIFACT_NAME.GRAMMAR_TRANSITIONS),
+				fetchArtifactJson<unknown>(ARTIFACT_NAME.POS_TAGS),
+				fetchArtifactJson<unknown>(ARTIFACT_NAME.GHOST_POS_TAGS),
+				fetchArtifactJson<unknown>(ARTIFACT_NAME.GRAMMAR_TRANSITIONS),
 			]);
 
-			if (grammarTransitionsData?.transitions == null) {
+			// A missing wrapper and a malformed ruleset are reported separately: the
+			// first points at the publishing step, the second at the payload itself.
+			if ((grammarTransitionsData as { transitions?: unknown })?.transitions == null) {
 				throw new Error(
 					`[scoring-pipeline] ${ARTIFACT_NAME.GRAMMAR_TRANSITIONS} is missing its \`transitions\` wrapper`,
 				);
 			}
+			if (!isGrammarTransitions(grammarTransitionsData)) {
+				throw new Error(
+					`[scoring-pipeline] ${ARTIFACT_NAME.GRAMMAR_TRANSITIONS} payload shape was invalid`,
+				);
+			}
+			if (!isPosTagsRecord(posTagsData)) {
+				throw new Error(`[scoring-pipeline] ${ARTIFACT_NAME.POS_TAGS} payload shape was invalid`);
+			}
+			if (!isPosTagsRecord(ghostPosTagsData)) {
+				throw new Error(
+					`[scoring-pipeline] ${ARTIFACT_NAME.GHOST_POS_TAGS} payload shape was invalid`,
+				);
+			}
 
 			setGrammarData({
-				posTags: posTagsData ?? {},
-				ghostPosTags: ghostPosTagsData ?? {},
+				posTags: posTagsData,
+				ghostPosTags: ghostPosTagsData,
 				grammarTransitions: grammarTransitionsData,
 			});
 
@@ -271,7 +345,16 @@ function applyGrammarFilter(
 	const dropped: string[] = [];
 
 	for (const entry of candidates) {
-		const candidateTags = posTags.get(entry.candidate.word.toLowerCase());
+		// The producer validates a multi-word term's *internal* grammar offline
+		// (boundary-clean, noun-headed, AUP-passed — spec §9), but nothing judges
+		// the transition into it. Exempting multi-word terms therefore let a noun
+		// this filter had just rejected re-enter wrapped in a bigram — "be" [AUX]
+		// dropped "quality" and then displayed "quality assurance". Only the term's
+		// first word takes part in the transition, so gate every term on that.
+		const surface = entry.candidate.word;
+		const firstSpace = surface.indexOf(' ');
+		const transitionWord = firstSpace === -1 ? surface : surface.slice(0, firstSpace);
+		const candidateTags = posTags.get(transitionWord.toLowerCase());
 
 		// If candidate has no tags (unknown word), let it pass to be safe
 		if (!candidateTags || candidateTags.length === 0) {
@@ -326,23 +409,38 @@ export interface RankCandidatesResult {
 	pipelineDebug: PipelineDebug;
 }
 
+/**
+ * Apply Stage 1, grammar, and nullable context-local LM evidence to candidates.
+ */
 export function rankCandidates(
 	candidates: ScoringCandidate[],
 	contextVector: Float32Array | null,
 	getWordVector: (word: string) => Float32Array | null,
 	lmLogits: Record<string, number> | null,
-	maxTenantFreq: number,
+	maxFreqByType: Record<TermType, number>,
 	previousWord: string,
+	getCanonicalLmEvidence?: (surface: string) => CanonicalLmEvidence | null,
 ): RankCandidatesResult {
 	// Stage 1
 	const stage1Results = candidates.map((candidate) => {
+		const termType = candidate.termType ?? 'word';
+		// Normalize freq within the candidate's own term-type population so a
+		// phrase (whose absolute counts are far below top unigrams) isn't crushed
+		// by the unigram max.
+		const maxFreq = maxFreqByType[termType] || 1;
 		const { semanticScore, freqScore, stage1Score } = scoreStage1(
 			candidate,
 			contextVector,
 			getWordVector,
-			maxTenantFreq,
+			maxFreq,
 		);
-		return { candidate, semanticScore, freqScore, stage1Score };
+		// Multi-word units get an NPMI association boost (Stage-1 only).
+		let adjustedStage1 = stage1Score;
+		if (termType !== 'word' && typeof candidate.association === 'number') {
+			const assoc = Math.max(0, Math.min(1, candidate.association));
+			adjustedStage1 = stage1Score * (1 + ASSOCIATION_BOOST * assoc);
+		}
+		return { candidate, semanticScore, freqScore, stage1Score: adjustedStage1 };
 	});
 	const stage1Survivors: typeof stage1Results = [];
 	const stage1Rejected: string[] = [];
@@ -363,22 +461,71 @@ export function rankCandidates(
 		const values = Object.values(lmLogits);
 		if (values.length > 0) lmMax = Math.max(...values);
 	}
+	const canonicalEvidenceBySurface = new Map<string, CanonicalLmEvidence>();
+	const maxLmRankingValueByTierAndContext = new Map<string, number>();
+	for (const entry of filtered) {
+		const evidence = getCanonicalLmEvidence?.(entry.candidate.word) ?? null;
+		if (!evidence) {
+			continue;
+		}
+		canonicalEvidenceBySurface.set(entry.candidate.word, evidence);
+		const rankingValue =
+			evidence.source === 'canonical-full-surface'
+				? evidence.meanTokenLogProbability
+				: evidence.rawLogit;
+		if (rankingValue !== undefined && Number.isFinite(rankingValue)) {
+			const key = `${evidence.source}\u0000${evidence.contextKey}`;
+			const current = maxLmRankingValueByTierAndContext.get(key) ?? -Infinity;
+			if (rankingValue > current) {
+				maxLmRankingValueByTierAndContext.set(key, rankingValue);
+			}
+		}
+	}
 
 	const scored: ScoredCandidate[] = filtered.map((entry) => {
+		const termType = entry.candidate.termType ?? 'word';
+		const isMultiWord = termType !== 'word';
 		let lmScore = 0;
 		let finalScore = entry.stage1Score;
-
-		if (lmLogits && lmMax >= LM_GATE_THRESHOLD) {
+		let lmEvidence = canonicalEvidenceBySurface.get(entry.candidate.word) ?? null;
+		if (lmEvidence) {
+			const rankingValue =
+				lmEvidence.source === 'canonical-full-surface'
+					? lmEvidence.meanTokenLogProbability
+					: lmEvidence.rawLogit;
+			const maxRankingValue = maxLmRankingValueByTierAndContext.get(
+				`${lmEvidence.source}\u0000${lmEvidence.contextKey}`,
+			);
+			if (rankingValue !== undefined && maxRankingValue !== undefined) {
+				lmEvidence = {
+					...lmEvidence,
+					score: Math.exp(rankingValue - maxRankingValue),
+				};
+			}
+		}
+		if (lmEvidence) {
+			lmScore = lmEvidence.score;
+			finalScore = STAGE1_WEIGHT * entry.stage1Score + STAGE2_WEIGHT * lmScore;
+		} else if (!isMultiWord && lmLogits && lmMax >= LM_GATE_THRESHOLD) {
+			// Backward-compatible network slow-lane path.
 			const rawLm = getLmScore(entry.candidate.word, lmLogits);
 
 			if (rawLm !== 0) {
 				const logitDiff = Math.log(rawLm) - Math.log(lmMax);
 				lmScore = Math.exp(logitDiff);
+				lmEvidence = {
+					contextKey: 'network',
+					score: lmScore,
+					separatorKind: 'whitespace',
+					source: 'network-logit',
+					totalSurfaceCharCount: entry.candidate.word.length,
+					// The legacy BE word map does not report canonical token depth.
+					totalTokenCount: 0,
+					verifiedCharCount: 0,
+					verifiedTokenCount: 0,
+				};
+				finalScore = STAGE1_WEIGHT * entry.stage1Score + STAGE2_WEIGHT * lmScore;
 			}
-			// Words absent from the prefix-filtered payload get lmScore = 0,
-			// not 0.05, so they don't outrank genuine LM predictions.
-
-			finalScore = STAGE1_WEIGHT * entry.stage1Score + STAGE2_WEIGHT * lmScore;
 		}
 
 		return {
@@ -386,7 +533,10 @@ export function rankCandidates(
 			freqScore: entry.freqScore,
 			semanticScore: entry.semanticScore,
 			lmScore,
+			lmEvidence,
 			finalScore,
+			stage1Score: entry.stage1Score,
+			termType,
 		};
 	});
 

package/src/pm-plugins/slow-lane-client.ts

@@ -9,7 +9,15 @@
 
 import { abortExp, EXPERIENCE_NAME, failExp, startExp, succeedExp } from '../analytics/ufo';
 
-import { isAutocompleteDebugEnabled } from './debug-mode';
+import { buildAutocompleteGatewayUrl } from './artifact-loader';
+import type {
+	BoundaryLmState,
+	BoundaryPrimeRequest,
+	ProgressiveSurfaceEvidence,
+	SurfaceScore,
+	SurfaceScoreRequest,
+} from './canonical-lm-scoring';
+import { CTC_STYLES, ctcTag } from './debug-mode';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -29,8 +37,6 @@ export interface TypeaheadEncodingsResponse {
 
 // eslint-disable-next-line require-unicode-regexp
 const WORD_BOUNDARY_CHARS = /[\s.,;:!?]/;
-// eslint-disable-next-line require-unicode-regexp
-const TRAILING_SLASH_REGEX = /\/$/;
 const DEFAULT_DEBOUNCE_MS = 300;
 
 /**
@@ -57,16 +63,28 @@ export interface SlowLaneClientConfig {
 	surface?: string;
 }
 
-export const createSlowLaneClient = (
-	config: SlowLaneClientConfig,
-): {
+export interface SlowLaneClient {
+	getBoundaryLmState?: (contextKey: string) => BoundaryLmState | null;
+	getCanonicalSurfaceCount?: () => number;
+	getCanonicalSurfaceTokenIds?: (surface: string) => number[] | null;
+	getContextInput?: () => string | null;
 	getContextVector: () => Float32Array | null;
 	getLmLogits: () => Record<string, number> | null;
+	getProgressiveSurfaceEvidence?: (
+		contextKey: string,
+		surface: string,
+	) => ProgressiveSurfaceEvidence | null;
+	getSurfaceScore?: (contextKey: string, surface: string) => SurfaceScore | null;
+	isReady?: () => boolean;
 	isWordBoundary: (text: string) => boolean;
+	primeBoundaryLm?: (input: BoundaryPrimeRequest) => void;
+	requestProgressiveSurfaceScores?: (input: SurfaceScoreRequest) => void;
 	setContextVector: (vector: Float32Array | null) => void;
 	setLmLogits: (logits: Record<string, number> | null) => void;
 	updateContext: (text: string) => void;
-} => {
+}
+
+export const createSlowLaneClient = (config: SlowLaneClientConfig): SlowLaneClient => {
 	const {
 		baseUrl,
 		sessionId: configSessionId,
@@ -88,6 +106,7 @@ export const createSlowLaneClient = (
 
 	let debounceTimer: ReturnType<typeof setTimeout> | null = null;
 	let lastRequestedText = '';
+	let storedContextInput: string | null = null;
 	let storedContextVector: Float32Array | null = null;
 	let storedLmLogits: Record<string, number> | null = null;
 	let requestSeq = 0;
@@ -98,7 +117,7 @@ export const createSlowLaneClient = (
 			return;
 		}
 
-		const url = `${baseUrl.replace(TRAILING_SLASH_REGEX, '')}${endpoint}`;
+		const url = buildAutocompleteGatewayUrl(endpoint, baseUrl);
 		const payload: TypeaheadEncodingsRequest = {
 			text,
 			session_id: sessionId,
@@ -110,20 +129,7 @@ export const createSlowLaneClient = (
 			...(surface ? { surface } : {}),
 		});
 
-		if (isAutocompleteDebugEnabled()) {
-			// eslint-disable-next-line no-console
-			console.groupCollapsed(
-				`%c[SlowLane] %c📤 Sending context | ${text.length} chars`,
-				'color: #9c27b0; font-weight: bold;',
-				'color: inherit;',
-			);
-			text.split('\n').forEach((line, i, arr) => {
-				// eslint-disable-next-line no-console
-				console.log(`  ${i === arr.length - 1 ? '▶' : ' '} ${line}`);
-			});
-			// eslint-disable-next-line no-console
-			console.groupEnd();
-		}
+		ctcTag('signal', `📤 network context sent · ${text.length} chars`, CTC_STYLES.section);
 
 		try {
 			const res = await fetchFn(url, {
@@ -133,6 +139,7 @@ export const createSlowLaneClient = (
 			});
 
 			if (!res.ok) {
+				storedContextInput = null;
 				storedContextVector = null;
 				storedLmLogits = null;
 				failExp(EXPERIENCE_NAME.SLOW_LANE_FETCH, requestId, {
@@ -141,14 +148,7 @@ export const createSlowLaneClient = (
 					isLocalLLM: false,
 					...(surface ? { surface } : {}),
 				});
-				if (isAutocompleteDebugEnabled()) {
-					// eslint-disable-next-line no-console
-					console.log(
-						`%c[SlowLane] %c❌ Request failed (${res.status})`,
-						'color: #9c27b0; font-weight: bold;',
-						'color: #f44336;',
-					);
-				}
+				ctcTag('signal', `❌ network request failed (${res.status})`, CTC_STYLES.bad);
 				return;
 			}
 
@@ -156,8 +156,10 @@ export const createSlowLaneClient = (
 
 			if (data.semantic_vector && Array.isArray(data.semantic_vector)) {
 				storedContextVector = new Float32Array(data.semantic_vector);
+				storedContextInput = text;
 			} else {
 				storedContextVector = null;
+				storedContextInput = null;
 			}
 
 			if (data.lm_logits && typeof data.lm_logits === 'object') {
@@ -166,28 +168,13 @@ export const createSlowLaneClient = (
 				storedLmLogits = null;
 			}
 
-			if (isAutocompleteDebugEnabled()) {
-				// eslint-disable-next-line no-console
-				console.groupCollapsed(
-					`%c[SlowLane] %c📥 Response received`,
-					'color: #9c27b0; font-weight: bold;',
-					'color: inherit;',
-				);
-				// eslint-disable-next-line no-console
-				console.log(
-					storedContextVector
-						? `✅ semantic_vector: ${storedContextVector.length} dims`
-						: '❌ No semantic_vector',
-				);
-				// eslint-disable-next-line no-console
-				console.log(
-					storedLmLogits
-						? `✅ lm_logits: ${Object.keys(storedLmLogits).length} tokens`
-						: '❌ No lm_logits',
-				);
-				// eslint-disable-next-line no-console
-				console.groupEnd();
-			}
+			ctcTag(
+				'signal',
+				`📥 network response · ${
+					storedContextVector ? `semantic ✅ ${storedContextVector.length}d` : 'semantic ❌'
+				} · ${storedLmLogits ? `logits ✅ ${Object.keys(storedLmLogits).length}tok` : 'logits ❌'}`,
+				CTC_STYLES.section,
+			);
 
 			succeedExp(EXPERIENCE_NAME.SLOW_LANE_FETCH, requestId, {
 				textLength: text.length,
@@ -204,6 +191,7 @@ export const createSlowLaneClient = (
 			});
 			// eslint-disable-next-line no-unused-vars
 		} catch (e) {
+			storedContextInput = null;
 			storedContextVector = null;
 			storedLmLogits = null;
 			failExp(EXPERIENCE_NAME.SLOW_LANE_FETCH, requestId, {
@@ -211,14 +199,7 @@ export const createSlowLaneClient = (
 				isLocalLLM: false,
 				...(surface ? { surface } : {}),
 			});
-			if (isAutocompleteDebugEnabled()) {
-				// eslint-disable-next-line no-console
-				console.log(
-					'%c[SlowLane] %c❌ Network error — context cleared',
-					'color: #9c27b0; font-weight: bold;',
-					'color: #f44336;',
-				);
-			}
+			ctcTag('signal', '❌ network error — context cleared', CTC_STYLES.bad);
 		} finally {
 			if (inflightRequestId === requestId) {
 				inflightRequestId = null;
@@ -247,9 +228,11 @@ export const createSlowLaneClient = (
 
 	return {
 		updateContext: updateContextDebounced,
+		getContextInput: () => storedContextInput,
 		getContextVector: () => storedContextVector,
 		getLmLogits: () => storedLmLogits,
 		setContextVector: (vector) => {
+			storedContextInput = null;
 			storedContextVector = vector;
 		},
 		setLmLogits: (logits) => {
@@ -259,16 +242,118 @@ export const createSlowLaneClient = (
 	};
 };
 
-let defaultSlowLaneClient: ReturnType<typeof createSlowLaneClient> | null = null;
+export type SlowLaneClientKind = 'localLlm' | 'server';
+
+export interface SlowLaneClientRegistration {
+	clientId: string;
+	kind: SlowLaneClientKind;
+}
+
+export interface SlowLaneClientStatus {
+	canonicalScoringSupported: boolean;
+	canonicalSurfaceCount: number | null;
+	clientId: string | null;
+	clientKind: SlowLaneClientKind | null;
+	localModelReady: boolean | null;
+	registered: boolean;
+}
+
+let defaultSlowLaneClient: SlowLaneClient | null = null;
+let defaultSlowLaneClientRegistration: SlowLaneClientRegistration | null = null;
+
+const supportsCanonicalSurfaceScoring = (client: SlowLaneClient | null): boolean =>
+	typeof client?.primeBoundaryLm === 'function' &&
+	typeof client?.requestProgressiveSurfaceScores === 'function';
 
 export const setDefaultSlowLaneClient = (
-	client: ReturnType<typeof createSlowLaneClient> | null,
+	client: SlowLaneClient | null,
+	registration?: SlowLaneClientRegistration,
 ): void => {
 	defaultSlowLaneClient = client;
+	defaultSlowLaneClientRegistration = client
+		? (registration ?? {
+				clientId: 'untracked',
+				kind: supportsCanonicalSurfaceScoring(client) ? 'localLlm' : 'server',
+			})
+		: null;
+};
+
+/**
+ * Clear the shared client only when the caller still owns the registration.
+ *
+ * Multiple editor instances can briefly overlap during a React/editor remount.
+ * An older instance must not disconnect the newer instance when its delayed
+ * teardown runs after the newer client has registered.
+ */
+export const clearDefaultSlowLaneClient = (client: SlowLaneClient): boolean => {
+	if (defaultSlowLaneClient !== client) {
+		return false;
+	}
+	defaultSlowLaneClient = null;
+	defaultSlowLaneClientRegistration = null;
+	return true;
+};
+
+export const getDefaultSlowLaneClientStatus = (): SlowLaneClientStatus => {
+	const canonicalScoringSupported = supportsCanonicalSurfaceScoring(defaultSlowLaneClient);
+	const isLocalClient = defaultSlowLaneClientRegistration?.kind === 'localLlm';
+	return {
+		registered: defaultSlowLaneClient !== null,
+		clientId: defaultSlowLaneClientRegistration?.clientId ?? null,
+		clientKind: defaultSlowLaneClientRegistration?.kind ?? null,
+		canonicalScoringSupported,
+		localModelReady:
+			isLocalClient && typeof defaultSlowLaneClient?.isReady === 'function'
+				? defaultSlowLaneClient.isReady()
+				: null,
+		canonicalSurfaceCount:
+			canonicalScoringSupported &&
+			typeof defaultSlowLaneClient?.getCanonicalSurfaceCount === 'function'
+				? defaultSlowLaneClient.getCanonicalSurfaceCount()
+				: null,
+	};
 };
 
 export const getStoredContextVector = (): Float32Array | null =>
 	defaultSlowLaneClient?.getContextVector() ?? null;
 
+export const getStoredContextInput = (): string | null =>
+	defaultSlowLaneClient?.getContextInput?.() ?? null;
+
 export const getStoredLmLogits = (): Record<string, number> | null =>
 	defaultSlowLaneClient?.getLmLogits() ?? null;
+
+export const getBoundaryLmState = (contextKey: string): BoundaryLmState | null =>
+	defaultSlowLaneClient?.getBoundaryLmState?.(contextKey) ?? null;
+
+export const getCanonicalSurfaceTokenIds = (surface: string): number[] | null =>
+	defaultSlowLaneClient?.getCanonicalSurfaceTokenIds?.(surface) ?? null;
+
+export const getSurfaceScore = (contextKey: string, surface: string): SurfaceScore | null =>
+	defaultSlowLaneClient?.getSurfaceScore?.(contextKey, surface) ?? null;
+
+export const getProgressiveSurfaceEvidence = (
+	contextKey: string,
+	surface: string,
+): ProgressiveSurfaceEvidence | null =>
+	defaultSlowLaneClient?.getProgressiveSurfaceEvidence?.(contextKey, surface) ?? null;
+
+export const primeBoundaryLm = (input: BoundaryPrimeRequest): void => {
+	defaultSlowLaneClient?.primeBoundaryLm?.(input);
+};
+
+export const requestProgressiveSurfaceScores = (input: SurfaceScoreRequest): void => {
+	defaultSlowLaneClient?.requestProgressiveSurfaceScores?.(input);
+};
+
+export const isCanonicalSurfaceScoringSupported = (): boolean =>
+	supportsCanonicalSurfaceScoring(defaultSlowLaneClient);
+
+/**
+ * How many surfaces the canonical token map currently holds. Goes from zero to
+ * its final size once the artifact lands, which is the only point at which
+ * `getCanonicalSurfaceTokenIds` starts answering — so callers memoising over
+ * that lookup can use this to detect the transition.
+ */
+export const getCanonicalSurfaceCount = (): number =>
+	defaultSlowLaneClient?.getCanonicalSurfaceCount?.() ?? 0;