@oscharko-dev/keiko-server 0.2.0

package/dist/editor/inlineCompletionRoutes.js

@@ -0,0 +1,404 @@
+// BFF routes for governed editor inline completion / ghost text (Issue #1200, ADR-0042 D5/D6).
+//
+//   POST /api/editor/inline-completion           — produce a single ghost-text continuation.
+//   POST /api/editor/inline-completion/telemetry — record content-free acceptance/rejection counts.
+//
+// Inline completion is model-only and GATED. Unlike the #1199 completion gateway there is no
+// deterministic ghost-text tier: the route runs the model ONLY when the completion-model selection
+// (#1210) elects an aligned ("instruct"/"edit-tuned") suffix-aware (FIM) model in budget, and only
+// when the interaction mode fits the trigger — an "automatic" (as-you-type) request requires a FAST
+// FIM model, an "explicit" request additionally accepts a slower manual-invoke FIM model. When no
+// governed model is usable, the feature is disabled by policy, or the per-root rate limit is hit, the
+// route returns ZERO items so the editor degrades to the deterministic completion gateway (#1199) —
+// never a silent ungoverned model (ADR-0042 D5; Acceptance Criteria 1/4).
+//
+// Model-assisted inline completion enriches its prompt with governed coding context (#1211,
+// `purpose: "inline"` — repository search only; embedding-cost providers are excluded as
+// keystroke-sensitive), assembled server-side and recorded as content-free evidence. The response is
+// content-free apart from the reviewable `insertText` ghost text: a source/provenance rollup with a
+// SHA-256 prompt hash, never the prompt, the buffer, or any retrieved excerpt. The browser never
+// reaches the Model Gateway, retrieval, or any provider directly (Acceptance Criterion 5). Request
+// pacing is bounded server-side by a per-root rate limiter (cooldown + window cap) plus the per-call
+// cost ceiling and an as-you-type latency budget; output is bounded by a hard character cap.
+import { CODING_CONTEXT_BUDGETS, CODING_CONTEXT_SCHEMA_VERSION, EDITOR_INLINE_COMPLETION_SCHEMA_VERSION, isValidScopePath, parseEditorInlineCompletionRequest, parseEditorInlineCompletionTelemetry, stripUnsafeFormatChars, toCodingContextWirePack, } from "@oscharko-dev/keiko-contracts";
+import { Gateway, selectCompletionModel } from "@oscharko-dev/keiko-model-gateway";
+import { errorBody } from "../routes.js";
+import { currentGatewayConfig } from "../deps.js";
+import { readJsonObject, resolveRoot, runFilesHandler } from "../files.js";
+import { assembleCodingContext } from "./codingContext.js";
+import { recordCodingContextEvidence } from "./codingContextEvidence.js";
+import { recordEditorCompletionModelEvidence } from "./completionModelEvidence.js";
+import { recordInlineCompletionTelemetryEvidence } from "./inlineCompletionTelemetryEvidence.js";
+import { clientAbortSignal, resolveOverlayPath } from "./languageRoutes.js";
+import { buildInlineCompletionPrompt, generateInlineCompletion, } from "./editorInlineCompletionModel.js";
+import { createInlineCompletionRateLimiter, } from "./inlineCompletionRateLimiter.js";
+import { estimateEditorModelReservationTokens, settleModelUsage, sharedEditorModelTokenBudget, } from "./editorModelTokenBudget.js";
+// Body cap: the overlay buffer may be up to the document-size cap; allow 64 KiB of JSON on top. The
+// language-service document cap is reused via the coding-context completion budget's source ceiling.
+const MAX_INLINE_BODY_BYTES = 1_048_576 + 64 * 1024;
+const MAX_TELEMETRY_BODY_BYTES = 16 * 1024;
+// Content-free identifier of the inline-completion governance policy version (audit correlation).
+const INLINE_COMPLETION_GATEWAY_POLICY_VERSION = "editor-inline-completion/1";
+// Hard upper bound on generated ghost-text length; `maxOutputTokens` may lower it (≈4 chars/token).
+const MAX_INLINE_INSERT_TEXT_CHARS = 2_000;
+const APPROX_CHARS_PER_TOKEN = 4;
+const MAX_CONTEXT_CHANGED_FILES = 64;
+// p95 latency budget for as-you-type ghost text (ADR-0042 D5): a fast FIM call self-cancels past it.
+const MODEL_AS_YOU_TYPE_TIMEOUT_MS = 750;
+// Policy/configuration gate (Acceptance Criterion 7). The feature is ENABLED by default; a deployment
+// disables it by setting this env var to a falsy token.
+const INLINE_COMPLETION_POLICY_ENV = "KEIKO_EDITOR_INLINE_COMPLETION";
+const INLINE_COMPLETION_MAX_COST_CLASS_ENV = "KEIKO_EDITOR_INLINE_COMPLETION_MAX_COST_CLASS";
+const DEFAULT_INLINE_COMPLETION_MAX_COST_CLASS = "low";
+const COST_CLASS_RANK = { low: 0, medium: 1, high: 2 };
+const DISABLE_TOKENS = new Set(["0", "false", "off", "no", "disabled"]);
+// Process-wide default limiter: shared so pacing spans requests within a server lifetime.
+const sharedRateLimiter = createInlineCompletionRateLimiter();
+// Default chat seam: route the elected model through the Model Gateway, server-side only.
+function defaultChatFactory(config, modelId) {
+    const gateway = new Gateway(config);
+    return async (chatRequest, chatSignal) => {
+        const response = await gateway.chat({
+            modelId,
+            messages: [
+                { role: "system", content: chatRequest.system },
+                { role: "user", content: chatRequest.user },
+            ],
+            cancellationSignal: chatSignal,
+        });
+        return { content: response.content, usage: response.usage };
+    };
+}
+/** Whether inline completion is enabled by deployment policy (default on; env toggle off). */
+export function isInlineCompletionEnabledByPolicy(env) {
+    const raw = env?.[INLINE_COMPLETION_POLICY_ENV];
+    if (raw === undefined) {
+        return true;
+    }
+    return !DISABLE_TOKENS.has(raw.trim().toLowerCase());
+}
+function parseCostClass(value) {
+    const trimmed = value?.trim().toLowerCase();
+    if (trimmed === "low" || trimmed === "medium" || trimmed === "high") {
+        return trimmed;
+    }
+    return undefined;
+}
+function stricterCostClass(left, right) {
+    return COST_CLASS_RANK[left] <= COST_CLASS_RANK[right] ? left : right;
+}
+export function inlineCompletionMaxCostClassFromPolicy(env) {
+    return (parseCostClass(env?.[INLINE_COMPLETION_MAX_COST_CLASS_ENV]) ??
+        DEFAULT_INLINE_COMPLETION_MAX_COST_CLASS);
+}
+function effectiveMaxCostClass(request, env) {
+    const serverCeiling = inlineCompletionMaxCostClassFromPolicy(env);
+    return request.maxCostClass === undefined
+        ? serverCeiling
+        : stricterCostClass(serverCeiling, request.maxCostClass);
+}
+function redactPromptText(deps, value) {
+    const stripped = stripUnsafeFormatChars(value);
+    const redacted = deps.redactor(stripped);
+    return typeof redacted === "string" ? redacted : stripped;
+}
+function isRouteResult(value) {
+    return typeof value === "object" && value !== null && "status" in value && "body" in value;
+}
+function noItemOutcome(mode, degradeReason, modelId, latencyClass) {
+    return { item: null, modelMode: mode, degradeReason, modelId, latencyClass, contextSources: [] };
+}
+function buildContextRequest(request) {
+    return {
+        schemaVersion: CODING_CONTEXT_SCHEMA_VERSION,
+        purpose: "inline",
+        documentPath: request.document.path,
+        symbol: request.context?.symbol,
+        queryText: request.context?.queryText,
+        changedFiles: request.context?.changedFiles,
+        capsuleId: request.context?.capsuleId,
+        capsuleSetId: request.context?.capsuleSetId,
+    };
+}
+function effectiveContextBudgetBytes(request) {
+    return Math.min(CODING_CONTEXT_BUDGETS.inline.budgetBytes, Math.max(0, Math.trunc(request.contextBudgetBytes)));
+}
+function effectiveMaxInsertTextChars(request) {
+    const fromTokens = request.maxOutputTokens === undefined
+        ? MAX_INLINE_INSERT_TEXT_CHARS
+        : request.maxOutputTokens * APPROX_CHARS_PER_TOKEN;
+    return Math.min(MAX_INLINE_INSERT_TEXT_CHARS, fromTokens);
+}
+function modelSignal(selection, signal, timeoutMs) {
+    if (selection.mode !== "as-you-type") {
+        return signal;
+    }
+    return AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]);
+}
+// Whether the elected interaction mode is eligible for THIS trigger: as-you-type runs on either
+// trigger; the slower manual-invoke mode runs only on an explicit invocation, bounding per-keystroke
+// model cost (ADR-0042 D5).
+function modeEligibleForTrigger(selection, triggerKind) {
+    if (selection.mode === "as-you-type") {
+        return true;
+    }
+    return selection.mode === "manual" && triggerKind === "explicit";
+}
+// Map the coding-context source kinds that actually contributed an excerpt to the AC7 source vocab.
+function contextSourcesFromPack(pack) {
+    const mapping = {
+        "repo-search": "repository-context",
+        "local-knowledge": "local-knowledge",
+        memory: "memory",
+        "connected-context": "connected-context",
+    };
+    const sources = new Set();
+    for (const excerpt of pack.excerpts) {
+        const mapped = mapping[excerpt.citation.sourceKind];
+        if (mapped !== undefined) {
+            sources.add(mapped);
+        }
+    }
+    return [...sources];
+}
+function inlineGenerationInput(ctx, pack) {
+    return {
+        overlayText: ctx.request.document.text,
+        position: ctx.request.position,
+        languageId: ctx.request.document.languageId,
+        contextPack: pack,
+        maxInsertTextChars: effectiveMaxInsertTextChars(ctx.request),
+        redactText: (value) => redactPromptText(ctx.deps, value),
+    };
+}
+function maxOutputTokensForModel(config, modelId) {
+    const capability = config.capabilities?.find((candidate) => candidate.id === modelId);
+    return Math.max(1, capability?.maxOutputTokens ?? Math.ceil(MAX_INLINE_INSERT_TEXT_CHARS / 4));
+}
+function reserveInlineCompletion(ctx, input) {
+    const prompt = buildInlineCompletionPrompt(input);
+    return ctx.tokenBudget.tryReserve(ctx.realRoot, ctx.nowMs, estimateEditorModelReservationTokens(prompt, maxOutputTokensForModel(ctx.config, ctx.modelId)));
+}
+function recordInlineModelEvidence(ctx, generated) {
+    recordEditorCompletionModelEvidence(ctx.deps.evidenceStore, ctx.deps.redactor, {
+        modelId: ctx.modelId,
+        modelMode: ctx.selection.mode,
+        latencyClass: ctx.selection.latencyClass,
+        gatewayPolicyVersion: INLINE_COMPLETION_GATEWAY_POLICY_VERSION,
+        promptHash: generated.promptHash,
+        itemCount: generated.insertText === null ? 0 : 1,
+        truncated: generated.truncated,
+        usage: generated.usage,
+    }, ctx.nowMs);
+}
+function inlineOutcomeFromGenerated(ctx, pack, generated) {
+    const insertText = generated.insertText;
+    return {
+        item: insertText === null ? null : { insertText },
+        modelMode: ctx.selection.mode,
+        modelId: ctx.modelId,
+        latencyClass: ctx.selection.latencyClass,
+        promptHash: generated.promptHash,
+        contextSources: insertText === null ? [] : contextSourcesFromPack(pack),
+        ...(generated.usage === undefined ? {} : { usage: generated.usage }),
+    };
+}
+// Runs the elected model: assembles coding context (#1211), records content-free evidence, calls the
+// gateway through the injected chat factory, and filters the output. A failure throws to the caller,
+// which degrades.
+async function runElectedInlineModel(ctx) {
+    const pack = await assembleCodingContext(buildContextRequest(ctx.request), {
+        deps: ctx.deps,
+        realRoot: ctx.realRoot,
+        signal: ctx.signal,
+        nowMs: ctx.nowMs,
+        budgetBytes: effectiveContextBudgetBytes(ctx.request),
+    });
+    recordCodingContextEvidence(ctx.deps.evidenceStore, ctx.deps.redactor, toCodingContextWirePack(pack), ctx.nowMs);
+    const generationInput = inlineGenerationInput(ctx, pack);
+    const reservation = reserveInlineCompletion(ctx, generationInput);
+    if (reservation === undefined) {
+        return noItemOutcome(ctx.selection.mode, undefined, ctx.modelId, ctx.selection.latencyClass);
+    }
+    const generated = await generateInlineCompletion(generationInput, ctx.chatFactory(ctx.config, ctx.modelId), ctx.signal);
+    settleModelUsage(reservation, generated.usage);
+    recordInlineModelEvidence(ctx, generated);
+    return inlineOutcomeFromGenerated(ctx, pack, generated);
+}
+// Order of gates: gateway configured → model selection (cost ceiling + aligned-FIM guardrail, in
+// selectCompletionModel) → trigger/mode eligibility. (Policy and rate limiting are applied by the
+// caller around this decision.)
+function decideInlineModel(request, deps) {
+    const config = currentGatewayConfig(deps);
+    if (config === undefined) {
+        return {
+            kind: "skip",
+            outcome: noItemOutcome("deterministic", "no-infilling-model", undefined, undefined),
+        };
+    }
+    const selection = selectCompletionModel(config, {
+        maxCostClass: effectiveMaxCostClass(request, deps.env),
+    });
+    const modelId = selection.modelId;
+    if (selection.mode === "deterministic" ||
+        modelId === undefined ||
+        !modeEligibleForTrigger(selection, request.triggerKind)) {
+        return {
+            kind: "skip",
+            outcome: noItemOutcome(selection.mode, selection.degradeReason, modelId, selection.latencyClass),
+        };
+    }
+    return { kind: "run", selection, modelId, config };
+}
+// True when the per-root request-rate limiter (#1200) blocks the model tier. The token ceiling
+// (#1206 LLM10) reserves immediately before the provider call once the prompt is known.
+function inlineModelTierRateBlocked(realRoot, nowMs, limiter) {
+    return !limiter.tryAcquire(realRoot, nowMs);
+}
+// Decides whether the gated model tier runs and, if so, runs it. Order: policy → model decision →
+// per-root request and token ceilings → run (a model/retrieval failure degrades to zero items).
+async function runInlineModelTier(request, realRoot, signal, deps, options) {
+    const now = options.now ?? Date.now;
+    if (!isInlineCompletionEnabledByPolicy(deps.env)) {
+        return noItemOutcome("deterministic", undefined, undefined, undefined);
+    }
+    const decision = decideInlineModel(request, deps);
+    if (decision.kind === "skip") {
+        return decision.outcome;
+    }
+    const { selection, modelId, config } = decision;
+    const limiter = options.rateLimiter ?? sharedRateLimiter;
+    const tokenBudget = options.tokenBudget ?? sharedEditorModelTokenBudget;
+    if (inlineModelTierRateBlocked(realRoot, now(), limiter)) {
+        // Request rate (#1200) hit: render no ghost text (degrade to #1199).
+        return noItemOutcome(selection.mode, undefined, modelId, selection.latencyClass);
+    }
+    try {
+        const outcome = await runElectedInlineModel({
+            request,
+            realRoot,
+            signal: modelSignal(selection, signal, options.asYouTypeTimeoutMs ?? MODEL_AS_YOU_TYPE_TIMEOUT_MS),
+            deps,
+            selection,
+            modelId,
+            chatFactory: options.chatFactory ?? defaultChatFactory,
+            config,
+            nowMs: now(),
+            tokenBudget,
+        });
+        return outcome;
+    }
+    catch {
+        // ADR-0042 D5 / AC1: a model or retrieval failure renders no ghost text; it never breaks the route.
+        return noItemOutcome(selection.mode, selection.degradeReason, modelId, selection.latencyClass);
+    }
+}
+// ─── Request sanitisation (mirrors the completion gateway's containment checks) ──────────────────
+function dedupeChangedFiles(paths) {
+    return [...new Set(paths)];
+}
+function invalidChangedFiles(message) {
+    return { status: 400, body: errorBody("INVALID_REQUEST", message) };
+}
+function sanitizeChangedFiles(realRoot, changedFiles) {
+    if (changedFiles === undefined) {
+        return undefined;
+    }
+    const deduped = dedupeChangedFiles(changedFiles);
+    if (deduped.length > MAX_CONTEXT_CHANGED_FILES) {
+        return invalidChangedFiles(`context.changedFiles must contain at most ${MAX_CONTEXT_CHANGED_FILES.toString()} paths.`);
+    }
+    for (const changed of deduped) {
+        if (!isValidScopePath(changed, { mustBeRelative: true })) {
+            return invalidChangedFiles(`context.changedFiles contains an invalid workspace-relative path: ${changed}`);
+        }
+        resolveOverlayPath(realRoot, changed);
+    }
+    return deduped.length > 0 ? deduped : undefined;
+}
+function sanitizeRequestContext(request, realRoot) {
+    const changedFiles = sanitizeChangedFiles(realRoot, request.context?.changedFiles);
+    if (isRouteResult(changedFiles)) {
+        return changedFiles;
+    }
+    if (request.context === undefined) {
+        return request;
+    }
+    return {
+        ...request,
+        context: {
+            ...(request.context.queryText === undefined ? {} : { queryText: request.context.queryText }),
+            ...(request.context.symbol === undefined ? {} : { symbol: request.context.symbol }),
+            ...(request.context.capsuleId === undefined ? {} : { capsuleId: request.context.capsuleId }),
+            ...(request.context.capsuleSetId === undefined
+                ? {}
+                : { capsuleSetId: request.context.capsuleSetId }),
+            ...(changedFiles === undefined ? {} : { changedFiles }),
+        },
+    };
+}
+// ─── Wire-response assembly ──────────────────────────────────────────────────────────────────────
+function buildProvenance(outcome, produced) {
+    const sources = produced
+        ? ["model-assisted", ...outcome.contextSources]
+        : [];
+    return {
+        sources: [...new Set(sources)],
+        modelMode: outcome.modelMode,
+        ...(outcome.degradeReason === undefined ? {} : { degradeReason: outcome.degradeReason }),
+        ...(produced && outcome.modelId !== undefined ? { modelId: outcome.modelId } : {}),
+        ...(produced && outcome.latencyClass !== undefined
+            ? { latencyClass: outcome.latencyClass }
+            : {}),
+        ...(produced ? { gatewayPolicyVersion: INLINE_COMPLETION_GATEWAY_POLICY_VERSION } : {}),
+        ...(produced && outcome.promptHash !== undefined ? { promptHash: outcome.promptHash } : {}),
+    };
+}
+function buildWireResponse(outcome) {
+    const items = outcome.item === null ? [] : [{ insertText: outcome.item.insertText }];
+    return {
+        schemaVersion: EDITOR_INLINE_COMPLETION_SCHEMA_VERSION,
+        items,
+        provenance: buildProvenance(outcome, items.length > 0),
+    };
+}
+// ─── Routes ───────────────────────────────────────────────────────────────────────────────────
+export async function handleEditorInlineCompletion(ctx, deps, options = {}) {
+    const body = await readJsonObject(ctx.req, MAX_INLINE_BODY_BYTES);
+    if (isRouteResult(body)) {
+        return body;
+    }
+    const parsed = parseEditorInlineCompletionRequest(body);
+    if (!parsed.ok) {
+        return { status: 400, body: errorBody("INVALID_REQUEST", parsed.errors.join("; ")) };
+    }
+    const request = parsed.value;
+    return runFilesHandler(async () => {
+        const root = await resolveRoot(deps.store, request.root, deps.redactor);
+        // Containment check for the overlay document path (throws on escape → handled by runFilesHandler).
+        resolveOverlayPath(root.realRoot, request.document.path);
+        const sanitizedRequest = sanitizeRequestContext(request, root.realRoot);
+        if (isRouteResult(sanitizedRequest)) {
+            return sanitizedRequest;
+        }
+        const signal = clientAbortSignal(ctx);
+        const outcome = await runInlineModelTier(sanitizedRequest, root.realRoot, signal, deps, options);
+        return { status: 200, body: deps.redactor(buildWireResponse(outcome)) };
+    });
+}
+export async function handleEditorInlineCompletionTelemetry(ctx, deps, options = {}) {
+    const body = await readJsonObject(ctx.req, MAX_TELEMETRY_BODY_BYTES);
+    if (isRouteResult(body)) {
+        return body;
+    }
+    const parsed = parseEditorInlineCompletionTelemetry(body);
+    if (!parsed.ok) {
+        return { status: 400, body: errorBody("INVALID_REQUEST", parsed.errors.join("; ")) };
+    }
+    return runFilesHandler(async () => {
+        const root = await resolveRoot(deps.store, parsed.value.root, deps.redactor);
+        const now = options.now ?? Date.now;
+        recordInlineCompletionTelemetryEvidence(deps.evidenceStore, deps.redactor, { ...parsed.value, root: root.realRoot }, now());
+        return { status: 200, body: deps.redactor({ ok: true }) };
+    });
+}

package/dist/editor/inlineCompletionTelemetryEvidence.d.ts

@@ -0,0 +1,5 @@
+import type { EditorInlineCompletionTelemetryReport, EvidenceStore } from "@oscharko-dev/keiko-contracts";
+import type { Redactor } from "../deps.js";
+export declare const EDITOR_INLINE_COMPLETION_TELEMETRY_EVIDENCE_SCHEMA_VERSION: "1";
+export declare function recordInlineCompletionTelemetryEvidence(store: EvidenceStore, redactor: Redactor, report: EditorInlineCompletionTelemetryReport, emittedAtMs: number): string;
+//# sourceMappingURL=inlineCompletionTelemetryEvidence.d.ts.map

package/dist/editor/inlineCompletionTelemetryEvidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inlineCompletionTelemetryEvidence.d.ts","sourceRoot":"","sources":["../../src/editor/inlineCompletionTelemetryEvidence.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,qCAAqC,EACrC,aAAa,EACd,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,eAAO,MAAM,0DAA0D,EAAG,GAAY,CAAC;AAWvF,wBAAgB,uCAAuC,CACrD,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,qCAAqC,EAC7C,WAAW,EAAE,MAAM,GAClB,MAAM,CA0BR"}

package/dist/editor/inlineCompletionTelemetryEvidence.js

@@ -0,0 +1,42 @@
+// Content-free audit linkage for inline-completion acceptance/rejection telemetry (Issue #1200,
+// Acceptance Criterion 6; EU AI Act Reg. (EU) 2024/1689 Art. 12 record-keeping). The record carries
+// only counts, latency aggregates, plus a HASH of the workspace root — never the root path itself,
+// never buffer text, inserted ghost text, prompts, or any code content. It is the auditable
+// acceptance-rate and p50/p95 latency signal the product can report without persisting what the user
+// typed or accepted.
+import { createHash } from "node:crypto";
+export const EDITOR_INLINE_COMPLETION_TELEMETRY_EVIDENCE_SCHEMA_VERSION = "1";
+function sha256Hex(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function telemetryEvidenceRunId(rootHash, emittedAtMs) {
+    const digest = sha256Hex(`${rootHash}\n${String(emittedAtMs)}`).slice(0, 16);
+    return `editor-inline-completion-telemetry-${digest}`;
+}
+export function recordInlineCompletionTelemetryEvidence(store, redactor, report, emittedAtMs) {
+    // Hash the root so the evidence never carries a workspace filesystem path.
+    const rootHash = sha256Hex(report.root);
+    const runId = telemetryEvidenceRunId(rootHash, emittedAtMs);
+    const manifest = {
+        editorInlineCompletionTelemetrySchemaVersion: EDITOR_INLINE_COMPLETION_TELEMETRY_EVIDENCE_SCHEMA_VERSION,
+        runId,
+        emittedAtMs,
+        rootHash,
+        offered: report.offered,
+        shown: report.shown,
+        accepted: report.accepted,
+        rejected: report.rejected,
+        ignored: report.ignored,
+        partiallyAccepted: report.partiallyAccepted,
+        requestCount: report.requestCount,
+        requestLatencyMsP50: report.requestLatencyMsP50,
+        requestLatencyMsP95: report.requestLatencyMsP95,
+    };
+    try {
+        store.put(runId, JSON.stringify(redactor(manifest)));
+    }
+    catch {
+        // Evidence persistence is best-effort; a write failure must not fail the telemetry report.
+    }
+    return runId;
+}

package/dist/editor/languageCancellation.d.ts

@@ -0,0 +1,19 @@
+import ts from "typescript";
+export declare class LanguageCancelledError extends Error {
+    constructor();
+}
+export type CancellationReason = "aborted" | "timeout";
+export interface LanguageCancellation {
+    isCancellationRequested(): boolean;
+    throwIfCancellationRequested(): void;
+    reason(): CancellationReason | undefined;
+    hostToken(): ts.HostCancellationToken;
+}
+export interface DeadlineCancellationOptions {
+    readonly signal?: AbortSignal | undefined;
+    readonly deadlineMs: number;
+    readonly now?: (() => number) | undefined;
+}
+export declare function createDeadlineCancellation(options: DeadlineCancellationOptions): LanguageCancellation;
+export declare function isCancellation(error: unknown): boolean;
+//# sourceMappingURL=languageCancellation.d.ts.map

package/dist/editor/languageCancellation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"languageCancellation.d.ts","sourceRoot":"","sources":["../../src/editor/languageCancellation.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,qBAAa,sBAAuB,SAAQ,KAAK;;CAKhD;AAED,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,SAAS,CAAC;AAEvD,MAAM,WAAW,oBAAoB;IACnC,uBAAuB,IAAI,OAAO,CAAC;IAEnC,4BAA4B,IAAI,IAAI,CAAC;IAGrC,MAAM,IAAI,kBAAkB,GAAG,SAAS,CAAC;IAEzC,SAAS,IAAI,EAAE,CAAC,qBAAqB,CAAC;CACvC;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CAC3C;AAED,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B,GACnC,oBAAoB,CA0BtB;AAID,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEtD"}

package/dist/editor/languageCancellation.js

@@ -0,0 +1,48 @@
+// Deadline + abort cancellation for the deterministic language service (Issue #1198). This bounds
+// "expensive analysis" two ways: a wall-clock deadline (so a pathological program can never block
+// the loopback BFF) and an AbortSignal (so a disconnected client request is honoured at the next
+// cooperative cancellation check). The TypeScript language service polls a HostCancellationToken at
+// function/class/module declaration boundaries during traversal and throws
+// `ts.OperationCanceledException`; the orchestrator additionally pre-checks the token before each
+// operation so an already-expired deadline or pre-aborted signal short-circuits flat files that
+// contain no such boundary. This module supplies that token and a provider-facing variant that
+// throws a transport-neutral `LanguageCancelledError`.
+import ts from "typescript";
+export class LanguageCancelledError extends Error {
+    constructor() {
+        super("language operation cancelled");
+        this.name = "LanguageCancelledError";
+    }
+}
+export function createDeadlineCancellation(options) {
+    const now = options.now ?? Date.now;
+    const deadline = now() + options.deadlineMs;
+    let reason;
+    const check = () => {
+        if (reason !== undefined)
+            return true;
+        if (options.signal?.aborted === true) {
+            reason = "aborted";
+            return true;
+        }
+        if (now() >= deadline) {
+            reason = "timeout";
+            return true;
+        }
+        return false;
+    };
+    return {
+        isCancellationRequested: check,
+        throwIfCancellationRequested: () => {
+            if (check())
+                throw new LanguageCancelledError();
+        },
+        reason: () => reason,
+        hostToken: () => ({ isCancellationRequested: check }),
+    };
+}
+// True when an error represents a cancellation — either the language service's own
+// `OperationCanceledException` or the provider-facing `LanguageCancelledError`.
+export function isCancellation(error) {
+    return error instanceof ts.OperationCanceledException || error instanceof LanguageCancelledError;
+}

package/dist/editor/languageProvider.d.ts

@@ -0,0 +1,39 @@
+import type { LanguageCompletionResult, LanguageDiagnostic, LanguageDocumentSymbol, LanguageFormattingOptions, LanguageHoverResult, LanguagePosition, LanguageProviderDescriptor, LanguageServiceLimits, LanguageTextEdit } from "@oscharko-dev/keiko-contracts";
+import type { WorkspaceFs } from "@oscharko-dev/keiko-workspace";
+import type { LanguageCancellation } from "./languageCancellation.js";
+export interface LanguageProviderContext {
+    readonly fs: WorkspaceFs;
+    readonly root: string;
+    readonly overlayPath: string;
+    readonly overlayText: string;
+    readonly languageId: string;
+    readonly limits: LanguageServiceLimits;
+    readonly cancellation: LanguageCancellation;
+}
+export interface LanguageProvider {
+    readonly descriptor: LanguageProviderDescriptor;
+    supports(languageId: string): boolean;
+    getDiagnostics(ctx: LanguageProviderContext): LanguageDiagnosticsRaw;
+    getCompletions(ctx: LanguageProviderContext, position: LanguagePosition): LanguageCompletionResult;
+    getHover(ctx: LanguageProviderContext, position: LanguagePosition): LanguageHoverResult;
+    getSymbols(ctx: LanguageProviderContext): LanguageSymbolsRaw;
+    getFormatting(ctx: LanguageProviderContext, options: LanguageFormattingOptions | undefined): LanguageFormattingRaw;
+}
+export interface LanguageDiagnosticsRaw {
+    readonly diagnostics: readonly LanguageDiagnostic[];
+    readonly truncated: boolean;
+}
+export interface LanguageSymbolsRaw {
+    readonly symbols: readonly LanguageDocumentSymbol[];
+    readonly truncated: boolean;
+}
+export interface LanguageFormattingRaw {
+    readonly edits: readonly LanguageTextEdit[];
+    readonly truncated: boolean;
+}
+export interface LanguageProviderRegistry {
+    resolve(languageId: string): LanguageProvider | undefined;
+    describe(): readonly LanguageProviderDescriptor[];
+}
+export declare function createLanguageProviderRegistry(providers: readonly LanguageProvider[], unavailableProviders?: readonly LanguageProviderDescriptor[]): LanguageProviderRegistry;
+//# sourceMappingURL=languageProvider.d.ts.map

package/dist/editor/languageProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"languageProvider.d.ts","sourceRoot":"","sources":["../../src/editor/languageProvider.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,wBAAwB,EACxB,kBAAkB,EAClB,sBAAsB,EACtB,yBAAyB,EACzB,mBAAmB,EACnB,gBAAgB,EAChB,0BAA0B,EAC1B,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAKtE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;CAC7C;AAID,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,0BAA0B,CAAC;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;IACtC,cAAc,CAAC,GAAG,EAAE,uBAAuB,GAAG,sBAAsB,CAAC;IACrE,cAAc,CACZ,GAAG,EAAE,uBAAuB,EAC5B,QAAQ,EAAE,gBAAgB,GACzB,wBAAwB,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,uBAAuB,EAAE,QAAQ,EAAE,gBAAgB,GAAG,mBAAmB,CAAC;IACxF,UAAU,CAAC,GAAG,EAAE,uBAAuB,GAAG,kBAAkB,CAAC;IAI7D,aAAa,CACX,GAAG,EAAE,uBAAuB,EAC5B,OAAO,EAAE,yBAAyB,GAAG,SAAS,GAC7C,qBAAqB,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACpD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACpD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;IAC1D,QAAQ,IAAI,SAAS,0BAA0B,EAAE,CAAC;CACnD;AAED,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,SAAS,gBAAgB,EAAE,EACtC,oBAAoB,GAAE,SAAS,0BAA0B,EAAO,GAC/D,wBAAwB,CAO1B"}

package/dist/editor/languageProvider.js

@@ -0,0 +1,11 @@
+// Provider abstraction for the deterministic language service (Issue #1198, Review Addendum 2). A
+// provider is a deterministic, model-free language-intelligence backend bound to a set of
+// `languageId`s. TypeScript/JavaScript is the first provider; the staged LSP expansion for
+// Java/Python/Rust/Go (#1213) registers further providers without any contract change. The registry
+// resolves a request's `languageId` to the provider that serves it.
+export function createLanguageProviderRegistry(providers, unavailableProviders = []) {
+    return {
+        resolve: (languageId) => providers.find((provider) => provider.supports(languageId)),
+        describe: () => [...providers.map((provider) => provider.descriptor), ...unavailableProviders],
+    };
+}

package/dist/editor/languageRoutes.d.ts

@@ -0,0 +1,15 @@
+import { type LanguageServiceErrorCode, type LanguageServiceLimits } from "@oscharko-dev/keiko-contracts";
+import { type RouteContext, type RouteResult } from "../routes.js";
+import type { UiHandlerDeps } from "../deps.js";
+export interface EditorLanguageRouteOptions {
+    /** Test-only deterministic limits seam; production keeps the default deadline. */
+    readonly limits?: LanguageServiceLimits | undefined;
+    /** Test-only deterministic clock seam; production keeps the real clock. */
+    readonly now?: (() => number) | undefined;
+}
+export declare const STATUS_BY_CODE: Readonly<Record<LanguageServiceErrorCode, number>>;
+export declare function resolveOverlayPath(realRoot: string, relativePath: string): string;
+export declare function clientAbortSignal(ctx: RouteContext): AbortSignal;
+export declare function handleEditorLanguage(ctx: RouteContext, deps: UiHandlerDeps, options?: EditorLanguageRouteOptions): Promise<RouteResult>;
+export declare function handleEditorLanguageCapabilities(): RouteResult;
+//# sourceMappingURL=languageRoutes.d.ts.map

package/dist/editor/languageRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"languageRoutes.d.ts","sourceRoot":"","sources":["../../src/editor/languageRoutes.ts"],"names":[],"mappings":"AASA,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC3B,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAa,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAShD,MAAM,WAAW,0BAA0B;IACzC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;IACpD,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CAC3C;AAID,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,wBAAwB,EAAE,MAAM,CAAC,CAQ7E,CAAC;AAaF,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAWjF;AAID,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,WAAW,CAahE;AAiBD,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,EACnB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,WAAW,CAAC,CAuBtB;AAED,wBAAgB,gCAAgC,IAAI,WAAW,CAE9D"}