@chengxianglibra/dsh-data-analysis 0.1.1 → 0.2.0

package/lib/semantic-browser/service.js

@@ -0,0 +1,106 @@
+import { realpath } from 'node:fs/promises';
+import { finishCleanup, PendingTasks } from "../lifecycle.js";
+import { boundedText, closed } from "../semantic-reference/contracts.js";
+import { semanticEnvironmentFingerprint } from "../semantic-reference/environment.js";
+import { abortable } from "../semantic-reference/rpc.js";
+import { CATALOG_MAX_BYTES, parseCatalogFailure, parseCatalogProjection, } from "./contracts.js";
+import { BROWSER_CATALOG_PROGRAM } from "./program.js";
+export class SemanticCatalogLoadError extends Error {
+    code = 'catalog-load-failed';
+    diagnostic;
+    constructor(diagnostic) {
+        super(diagnostic);
+        this.diagnostic = diagnostic;
+        this.name = 'SemanticCatalogLoadError';
+    }
+}
+/** Workspace-addressed read service; intentionally has no Agent or credential dependency. */
+export class SemanticBrowserService {
+    #host;
+    #lifetime = new AbortController();
+    #tasks = new PendingTasks();
+    #closing;
+    constructor(host) {
+        this.#host = host;
+    }
+    #assertOwner(id, workspacePath, root) {
+        const current = this.#host.getWorkspace(id);
+        if (!current || current.path !== workspacePath || this.#host.projectRoot(current) !== root)
+            throw new Error('workspace-changed');
+    }
+    read(payload, caller) {
+        return this.#tasks.track(this.#read(payload, caller));
+    }
+    async #read(payload, caller) {
+        const signal = AbortSignal.any([caller, this.#lifetime.signal]);
+        signal.throwIfAborted();
+        const request = closed(payload, ['workspaceId']);
+        const id = boundedText(request.workspaceId, 256);
+        const workspace = this.#host.getWorkspace(id);
+        if (!workspace)
+            throw new Error('workspace-unavailable');
+        const root = this.#host.projectRoot(workspace);
+        const runner = await abortable(this.#tasks.track(this.#host.resolve(root)), signal);
+        this.#assertOwner(id, workspace.path, root);
+        if (runner.status !== 'ready')
+            throw new Error('environment-failed');
+        const result = await runner.runChecked({
+            program: BROWSER_CATALOG_PROGRAM,
+            args: [runner.binding.projectRoot],
+            signal,
+            environmentOverlay: { MARIVO_TELEMETRY: 'off', PYTHONDONTWRITEBYTECODE: '1' },
+            limits: { timeoutMs: 30_000, stdoutMaxBytes: CATALOG_MAX_BYTES, stderrMaxBytes: 8192 },
+        });
+        signal.throwIfAborted();
+        if ((await realpath(root)) !== runner.binding.projectRoot)
+            throw new Error('workspace-changed');
+        this.#assertOwner(id, workspace.path, root);
+        signal.throwIfAborted();
+        if (result.exitCode !== 0) {
+            const failure = (() => {
+                try {
+                    return parseCatalogFailure(JSON.parse(result.stdout.toString('utf8')));
+                }
+                catch {
+                    return undefined;
+                }
+            })();
+            if (failure)
+                throw new SemanticCatalogLoadError(failure.message);
+            throw new Error('catalog-load-failed');
+        }
+        if (result.stdout.byteLength > CATALOG_MAX_BYTES)
+            throw new Error('catalog-too-large');
+        const projection = parseCatalogProjection(JSON.parse(result.stdout.toString('utf8')));
+        return {
+            ...projection,
+            workspaceId: id,
+            projectRoot: runner.binding.projectRoot,
+            environmentFingerprint: semanticEnvironmentFingerprint(id, runner.binding.fingerprint),
+            loadedAt: new Date().toISOString(),
+        };
+    }
+    close() {
+        this.dispose();
+        this.#closing ??= finishCleanup([() => this.#tasks.drain()]);
+        return this.#closing;
+    }
+    dispose() {
+        this.#lifetime.abort();
+    }
+}
+/** Preserve Marivo semantic diagnostics; keep unknown Python failures behind a fixed fallback. */
+export function browserFailure(error) {
+    const code = error instanceof Error && 'code' in error ? error.code : undefined;
+    if (error instanceof SemanticCatalogLoadError)
+        return `语义层模型加载失败：\n${error.diagnostic}`;
+    if (code === 'subprocess-timeout')
+        return '语义层加载超时，请检查模型后重试。';
+    if (code === 'subprocess-output-limit' ||
+        (error instanceof Error && error.message === 'catalog-too-large'))
+        return '语义层超过读取大小上限，未加载不完整目录。';
+    if (error instanceof Error &&
+        ['workspace-unavailable', 'workspace-changed'].includes(error.message))
+        return 'Workspace 已不可用或绑定发生变化，请重新选择。';
+    return '无法加载语义层，请检查项目模型与 Marivo Runtime 后重试。';
+}

package/lib/semantic-reference/bridge.js

@@ -0,0 +1,127 @@
+import { finishCleanup, PendingTasks } from "../lifecycle.js";
+import { parseProjection } from "./contracts.js";
+export const CATALOG_PROGRAM = String.raw `
+import contextlib, io, json, sys
+with contextlib.redirect_stdout(io.StringIO()):
+    import marivo.semantic as ms
+    from marivo.refs import RefPayloadV1, SemanticKind
+    catalog = ms.load(workspace_dir=sys.argv[1])
+    rows = []
+    for kind in SemanticKind:
+        for entry in catalog.items(kind).items:
+            definition = entry.details().context.business_definition
+            rows.append({"ref": RefPayloadV1.from_ref(entry.ref).to_dict(), "refKey": entry.ref.key,
+                         "name": entry.name, "businessDefinition": definition[:240] if definition else None})
+    result = {"kinds": [kind.value for kind in SemanticKind], "items": rows}
+print(json.dumps(result, ensure_ascii=True))
+`.trim();
+/** One plugin-owned cache, keyed by the exact Environment fingerprint. */
+export class SemanticReferenceBridge {
+    #slots = new Map();
+    #clock;
+    #disposed = false;
+    #tasks = new PendingTasks();
+    #closing;
+    constructor(clock = Date.now) {
+        this.#clock = clock;
+    }
+    async candidates(runner, signal) {
+        signal.throwIfAborted();
+        if (this.#disposed)
+            throw new Error('disposed');
+        const key = runner.binding.fingerprint;
+        if (runner.status !== 'ready') {
+            this.invalidate(key);
+            throw new Error('environment-failed');
+        }
+        let slot = this.#slots.get(key);
+        if (!slot) {
+            slot = {};
+            this.#slots.set(key, slot);
+        }
+        if (slot.snapshot && this.#clock() < slot.expires)
+            return slot.snapshot;
+        if (!slot.flight) {
+            const current = slot;
+            const controller = new AbortController();
+            const flight = {
+                controller,
+                waiters: 0,
+                promise: Promise.resolve({ kinds: [], items: [] }),
+            };
+            current.flight = flight;
+            flight.promise = this.#tasks
+                .track(this.#load(runner, controller.signal))
+                .then((projection) => {
+                if (!controller.signal.aborted &&
+                    !this.#disposed &&
+                    current.flight === flight &&
+                    runner.status === 'ready') {
+                    current.snapshot = projection;
+                    current.expires = this.#clock() + 30_000;
+                }
+                return projection;
+            })
+                .finally(() => {
+                if (current.flight === flight)
+                    current.flight = undefined;
+            });
+        }
+        const current = slot, flight = slot.flight;
+        flight.waiters++;
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (value, error) => {
+                if (settled)
+                    return;
+                settled = true;
+                signal.removeEventListener('abort', abort);
+                flight.controller.signal.removeEventListener('abort', loadAbort);
+                flight.waiters--;
+                if (!flight.waiters && current.flight === flight) {
+                    current.flight = undefined;
+                    flight.controller.abort();
+                }
+                if (error !== undefined)
+                    reject(error);
+                else
+                    resolve(value);
+            };
+            const abort = () => finish(undefined, new Error('cancelled'));
+            const loadAbort = () => finish(undefined, new Error('cancelled'));
+            signal.addEventListener('abort', abort, { once: true });
+            flight.controller.signal.addEventListener('abort', loadAbort, { once: true });
+            flight.promise.then((value) => finish(value), (error) => finish(undefined, error));
+            if (signal.aborted || flight.controller.signal.aborted)
+                abort();
+        });
+    }
+    async #load(runner, signal) {
+        const result = await runner.runChecked({
+            program: CATALOG_PROGRAM,
+            args: [runner.binding.projectRoot],
+            signal,
+            environmentOverlay: { MARIVO_TELEMETRY: 'off', PYTHONDONTWRITEBYTECODE: '1' },
+            limits: { timeoutMs: 30_000, stdoutMaxBytes: 32 * 1024 * 1024, stderrMaxBytes: 8192 },
+        });
+        signal.throwIfAborted();
+        if (result.exitCode !== 0)
+            throw new Error('catalog-load-failed');
+        return parseProjection(JSON.parse(result.stdout.toString('utf8')));
+    }
+    close() {
+        this.dispose();
+        this.#closing ??= finishCleanup([() => this.#tasks.drain()]);
+        return this.#closing;
+    }
+    invalidate(key) {
+        const slot = this.#slots.get(key);
+        this.#slots.delete(key);
+        slot?.flight?.controller.abort();
+    }
+    dispose() {
+        this.#disposed = true;
+        for (const key of this.#slots.keys())
+            this.invalidate(key);
+    }
+}

package/lib/semantic-reference/contracts.js

@@ -0,0 +1,127 @@
+/** Browser-safe wire contracts. These bounds do not reimplement Marivo's domain grammar. */
+export const CHANNEL = '/dsh-data-analysis';
+export const SOURCE = 'marivo-semantic';
+export const MAX_WIRE_BYTES = 1024 * 1024;
+export function closed(value, keys) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new Error('invalid-request');
+    const record = value;
+    if (Object.keys(record).length !== keys.length || keys.some((key) => !Object.hasOwn(record, key)))
+        throw new Error('invalid-request');
+    return record;
+}
+export function boundedText(value, max, empty = false) {
+    if (typeof value !== 'string' ||
+        value.length > max * 2 ||
+        (!empty && value.length === 0) ||
+        Array.from(value).length > max)
+        throw new Error('invalid-request');
+    return value;
+}
+export function parseJson(value, max = 16_384) {
+    const text = boundedText(value, max);
+    return JSON.parse(text);
+}
+export function parseRef(value) {
+    const r = closed(value, ['schema', 'kind', 'path']);
+    if (r.schema !== 'marivo.semantic_ref/v1')
+        throw new Error('invalid-request');
+    return Object.freeze({
+        schema: r.schema,
+        kind: boundedText(r.kind, 128),
+        path: boundedText(r.path, 2048),
+    });
+}
+export function refKey(ref) {
+    return `${ref.kind}:${ref.path}`;
+}
+export function parseEnvelope(value) {
+    const r = closed(value, ['schema', 'sessionId', 'environmentFingerprint', 'ref']);
+    if (r.schema !== 'dsh-data-analysis-semantic-reference/v1')
+        throw new Error('invalid-request');
+    return Object.freeze({
+        schema: r.schema,
+        sessionId: boundedText(r.sessionId, 256),
+        environmentFingerprint: boundedText(r.environmentFingerprint, 256),
+        ref: parseRef(r.ref),
+    });
+}
+export function envelopeJson(envelope) {
+    return JSON.stringify(parseEnvelope(envelope));
+}
+export function modelMarker(envelope) {
+    // Keep JSON inside one marker even when a valid domain path contains markup characters.
+    const json = JSON.stringify(parseRef(envelope.ref))
+        .replaceAll('<', '\\u003c')
+        .replaceAll('>', '\\u003e')
+        .replaceAll('&', '\\u0026');
+    return `<marivo-semantic-ref>${json}</marivo-semantic-ref>`;
+}
+export function parseCandidate(value) {
+    const r = closed(value, ['ref', 'refKey', 'name', 'businessDefinition']);
+    const ref = parseRef(r.ref);
+    if (r.refKey !== refKey(ref))
+        throw new Error('invalid-request');
+    return Object.freeze({
+        ref,
+        refKey: r.refKey,
+        name: boundedText(r.name, 2048),
+        businessDefinition: r.businessDefinition === null ? null : boundedText(r.businessDefinition, 240, true),
+    });
+}
+export function parseProjection(value) {
+    const r = closed(value, ['kinds', 'items']);
+    if (!Array.isArray(r.kinds) ||
+        r.kinds.length > 128 ||
+        !Array.isArray(r.items) ||
+        r.items.length > 100_000)
+        throw new Error('invalid-request');
+    const kinds = r.kinds.map((kind) => boundedText(kind, 128));
+    if (new Set(kinds).size !== kinds.length)
+        throw new Error('invalid-request');
+    const items = r.items.map(parseCandidate);
+    if (new Set(items.map((item) => item.refKey)).size !== items.length ||
+        items.some((item) => !kinds.includes(item.ref.kind)))
+        throw new Error('invalid-request');
+    return Object.freeze({ kinds: Object.freeze(kinds), items: Object.freeze(items) });
+}
+export function parseCandidatesRequest(value) {
+    const r = closed(value, ['version', 'sessionId', 'query', 'quoted']);
+    if (r.version !== 1 || typeof r.quoted !== 'boolean')
+        throw new Error('invalid-request');
+    return {
+        version: 1,
+        sessionId: boundedText(r.sessionId, 256),
+        query: boundedText(r.query, 128, true),
+        quoted: r.quoted,
+    };
+}
+export function parseCandidatesResponse(value) {
+    const r = closed(value, ['environmentFingerprint', 'items']);
+    if (!Array.isArray(r.items))
+        throw new Error('invalid-response');
+    const items = r.items.map((raw) => {
+        const item = closed(raw, ['ref', 'refKey', 'name', 'businessDefinition', 'section']);
+        const { section, ...candidate } = item;
+        if (section !== 'recent' && section !== 'kind' && section !== 'strict' && section !== 'fuzzy')
+            throw new Error('invalid-response');
+        return { ...parseCandidate(candidate), section };
+    });
+    return {
+        environmentFingerprint: boundedText(r.environmentFingerprint, 256),
+        items,
+    };
+}
+/** Browser selection identity only; preparation never reloads semantic content. */
+export function parsePrepareRequest(value) {
+    const r = closed(value, ['sessionId', 'workspaceId', 'environmentFingerprint', 'ref']);
+    return {
+        workspaceId: boundedText(r.workspaceId, 256),
+        envelope: parseEnvelope({
+            schema: 'dsh-data-analysis-semantic-reference/v1',
+            sessionId: r.sessionId,
+            environmentFingerprint: r.environmentFingerprint,
+            ref: r.ref,
+        }),
+    };
+}

package/lib/semantic-reference/environment.js

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto';
+/** Reference identity includes Harness ownership; the underlying Runtime stays unchanged. */
+export function semanticEnvironmentFingerprint(workspaceId, runtimeFingerprint) {
+    return createHash('sha256')
+        .update(JSON.stringify(['marivo-semantic-workspace/v1', workspaceId, runtimeFingerprint]))
+        .digest('hex');
+}
+/** Explicit selection establishes ownership; serialization never repairs it. */
+export function referenceEnvironmentResolver(host) {
+    const owners = new WeakMap();
+    return async (sessionId, purpose, workspaceId) => {
+        const agent = host.agent(sessionId);
+        if (!agent)
+            throw new Error('unknown-session');
+        const priorOwner = owners.get(agent);
+        const owner = purpose === 'reference' ? priorOwner?.workspace : host.workspace(sessionId);
+        if (purpose === 'prepare' && (!workspaceId || owner?.id !== workspaceId))
+            throw new Error('workspace-mismatch');
+        const checkOwner = () => {
+            if (!owner)
+                return;
+            const current = host.workspace(sessionId);
+            if (current.id !== owner.id || current.path !== owner.path)
+                throw new Error('workspace-changed');
+        };
+        checkOwner();
+        const bound = host.binding(agent);
+        if (purpose === 'reference' &&
+            (!owner || !bound || bound !== priorOwner?.binding || bound.root !== host.projectRoot(agent)))
+            throw new Error('environment-unbound');
+        const pending = purpose === 'reference' ? bound.environment : host.resolve(agent);
+        const expected = host.binding(agent);
+        const environment = await pending;
+        if (host.agent(sessionId) !== agent ||
+            host.binding(agent) !== expected ||
+            expected?.root !== host.projectRoot(agent))
+            throw new Error('environment-changed');
+        checkOwner();
+        if (!owner || !expected)
+            throw new Error('environment-unbound');
+        if (purpose !== 'reference')
+            owners.set(agent, { workspace: owner, binding: expected });
+        // Only the semantic surface uses the ownership fingerprint. Execution is delegated
+        // to the original runner, preserving its Runtime identity and dynamic health.
+        return {
+            binding: {
+                ...environment.binding,
+                fingerprint: semanticEnvironmentFingerprint(owner.id, environment.binding.fingerprint),
+            },
+            get status() {
+                return environment.status;
+            },
+            runChecked: (request) => environment.runChecked(request),
+        };
+    };
+}

package/lib/semantic-reference/index.js

@@ -0,0 +1,3 @@
+export { SemanticReferenceBridge } from "./bridge.js";
+export { registerSemanticReferenceRpc, SemanticReferenceService } from "./rpc.js";
+export { SemanticReferenceUsage } from "./usage.js";

package/lib/semantic-reference/labels.js

@@ -0,0 +1,16 @@
+/** Shared display labels and search aliases; object kinds still come from the live Catalog. */
+export const semanticKindLabels = {
+    domain: '业务域',
+    datasource: '数据源',
+    entity: '实体',
+    dimension: '维度',
+    measure: '度量',
+    time_dimension: '时间维度',
+    metric: '指标',
+    relationship: '关系',
+    event: '事件',
+    state_model: '状态模型',
+    period_calendar: '周期日历',
+    temporal_set: '时间集合',
+    work_schedule: '工作日程',
+};

package/lib/semantic-reference/rpc.js

@@ -0,0 +1,143 @@
+import { finishCleanup, PendingTasks } from "../lifecycle.js";
+import { registerPluginRpc } from "../rpc.js";
+import { SemanticReferenceBridge } from "./bridge.js";
+import { CHANNEL, closed, MAX_WIRE_BYTES, modelMarker, parseCandidatesRequest, parseEnvelope, parsePrepareRequest, } from "./contracts.js";
+import { search } from "./search.js";
+import { workspaceKey } from "./usage.js";
+/** Abort the caller's wait, without pretending to cancel the shared Environment resolver. */
+export async function abortable(promise, signal) {
+    return new Promise((resolve, reject) => {
+        const abort = () => {
+            signal.removeEventListener('abort', abort);
+            reject(new Error('cancelled'));
+        };
+        signal.addEventListener('abort', abort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener('abort', abort);
+            if (signal.aborted)
+                reject(new Error('cancelled'));
+            else
+                resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', abort);
+            reject(error);
+        });
+        if (signal.aborted)
+            abort();
+    });
+}
+export class SemanticReferenceService {
+    #resolve;
+    #usage;
+    #bridge;
+    #controller = new AbortController();
+    #closed = false;
+    #tasks = new PendingTasks();
+    #closing;
+    constructor(resolve, usage, bridge = new SemanticReferenceBridge()) {
+        this.#resolve = resolve;
+        this.#usage = usage;
+        this.#bridge = bridge;
+    }
+    async #environment(sessionId, signal, purpose = 'reference', workspaceId) {
+        const runner = await abortable(this.#tasks.track(this.#resolve(sessionId, purpose, workspaceId)), signal);
+        if (runner.status !== 'ready') {
+            this.#bridge.invalidate(runner.binding.fingerprint);
+            throw new Error('environment-failed');
+        }
+        return runner;
+    }
+    async #owner(envelope, signal) {
+        const runner = await this.#environment(envelope.sessionId, signal);
+        if (runner.binding.fingerprint !== envelope.environmentFingerprint)
+            throw new Error('environment-mismatch');
+        return runner;
+    }
+    handle(endpoint, payload, caller) {
+        return this.#tasks.track(this.#handle(endpoint, payload, caller));
+    }
+    async #handle(endpoint, payload, caller) {
+        if (this.#closed)
+            throw new Error('disposed');
+        const signal = AbortSignal.any([caller, this.#controller.signal]);
+        signal.throwIfAborted();
+        if (Buffer.byteLength(JSON.stringify(payload) ?? '') > MAX_WIRE_BYTES)
+            throw new Error('invalid-request');
+        if (endpoint === 'semantic-references/prepare') {
+            const { workspaceId, envelope } = parsePrepareRequest(payload);
+            const runner = await this.#environment(envelope.sessionId, signal, 'prepare', workspaceId);
+            if (runner.binding.fingerprint !== envelope.environmentFingerprint)
+                throw new Error('environment-mismatch');
+            signal.throwIfAborted();
+            return { envelope };
+        }
+        if (endpoint === 'semantic-references/candidates') {
+            const request = parseCandidatesRequest(payload);
+            const environment = await this.#environment(request.sessionId, signal, 'candidates');
+            const projection = await this.#bridge.candidates(environment, signal);
+            const scores = await abortable(this.#tasks.track(this.#usage.scores(workspaceKey(environment.binding.projectRoot))), signal);
+            // A live Agent may disappear or change binding while Catalog/storage work awaits.
+            const current = await this.#environment(request.sessionId, signal);
+            if (current.binding.fingerprint !== environment.binding.fingerprint)
+                throw new Error('environment-mismatch');
+            return {
+                environmentFingerprint: environment.binding.fingerprint,
+                items: search(projection, request.query, scores),
+            };
+        }
+        if (endpoint === 'semantic-references/selected' ||
+            endpoint === 'semantic-references/serialize') {
+            const request = closed(payload, ['envelope']), envelope = parseEnvelope(request.envelope);
+            const environment = await this.#owner(envelope, signal);
+            if (endpoint === 'semantic-references/serialize')
+                return { text: modelMarker(envelope) };
+            await this.#usage.selected(workspaceKey(environment.binding.projectRoot), envelope.ref, signal);
+            return { selected: true };
+        }
+        throw new Error('unknown-endpoint');
+    }
+    stop() {
+        this.#closed = true;
+        this.#controller.abort();
+        this.#bridge.dispose();
+    }
+    close() {
+        if (this.#closing)
+            return this.#closing;
+        this.stop();
+        this.#closing = finishCleanup([
+            () => this.#bridge.close(),
+            () => this.#tasks.drain(),
+            () => this.#usage.close(),
+        ]);
+        return this.#closing;
+    }
+}
+export function registerSemanticReferenceRpc(connection, service, browser) {
+    const unregister = registerPluginRpc(connection, CHANNEL, [
+        'semantic-references/prepare',
+        'semantic-references/candidates',
+        'semantic-references/selected',
+        'semantic-references/serialize',
+        'semantic-browser/catalog',
+    ], async (endpoint, payload, signal) => {
+        if (browser && endpoint === 'semantic-browser/catalog') {
+            return browser(endpoint, payload, signal);
+        }
+        try {
+            return { ok: true, value: await service.handle(endpoint, payload, signal) };
+        }
+        catch {
+            return {
+                ok: false,
+                error: {
+                    code: 'internal',
+                    message: 'Marivo semantic reference request failed',
+                    details: {},
+                },
+            };
+        }
+    });
+    let closing;
+    return () => (closing ??= finishCleanup([() => service.stop(), unregister, () => service.close()]));
+}

package/lib/semantic-reference/search.js

@@ -0,0 +1,95 @@
+import { semanticKindLabels } from "./labels.js";
+export function normalize(text) {
+    return text.normalize('NFKC').toLowerCase().trim().replace(/\s+/gu, ' ');
+}
+function tokens(text) {
+    return text.split(/[\s.:_-]+/u).filter(Boolean);
+}
+export function compareText(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function length(text) {
+    return Array.from(text).length;
+}
+export function dice(a, b) {
+    const grams = (text) => {
+        const chars = Array.from(text);
+        return new Set(chars.slice(0, -2).map((_, i) => chars.slice(i, i + 3).join('')));
+    };
+    const left = grams(a), right = grams(b);
+    if (!left.size || !right.size)
+        return 0;
+    return (2 * [...left].filter((gram) => right.has(gram)).length) / (left.size + right.size);
+}
+function match(item, query) {
+    const name = normalize(item.name), path = normalize(item.ref.path), key = normalize(item.refKey);
+    const fields = [name, path, key];
+    const label = Object.hasOwn(semanticKindLabels, item.ref.kind)
+        ? semanticKindLabels[item.ref.kind]
+        : '';
+    const all = [...fields, normalize(item.ref.kind), normalize(label)];
+    const searchTokens = all.flatMap(tokens);
+    if (fields.includes(query))
+        return { item, tier: 0, score: 1, field: 0 };
+    const prefixes = [...fields, ...searchTokens]
+        .map((value, field) => ({ value, field }))
+        .filter(({ value }) => value.startsWith(query));
+    if (prefixes.length) {
+        prefixes.sort((a, b) => length(a.value) - length(b.value) || a.field - b.field);
+        const best = prefixes[0];
+        return {
+            item,
+            tier: 1,
+            score: length(query) / length(best.value),
+            field: best.field < 3 ? best.field : 3,
+        };
+    }
+    const document = [...all, normalize(item.businessDefinition ?? '')].join(' ');
+    const qt = tokens(query);
+    if (qt.length && qt.every((token) => document.includes(token)))
+        return {
+            item,
+            tier: 2,
+            score: qt.reduce((sum, token) => sum + length(token), 0) / Math.max(1, length(document)),
+            field: 0,
+        };
+    return {
+        item,
+        tier: 3,
+        score: length(query) < 3
+            ? 0
+            : Math.max(...[name, ...tokens(path), path].map((value) => dice(query, value))),
+        field: 0,
+    };
+}
+export function search(projection, rawQuery, usage = new Map()) {
+    const query = normalize(rawQuery);
+    const heat = (a, b) => (usage.get(b.refKey)?.count ?? 0) - (usage.get(a.refKey)?.count ?? 0) ||
+        (usage.get(b.refKey)?.last ?? 0) - (usage.get(a.refKey)?.last ?? 0);
+    const fallback = (a, b) => projection.kinds.indexOf(a.ref.kind) - projection.kinds.indexOf(b.ref.kind) ||
+        compareText(a.refKey, b.refKey);
+    if (!query) {
+        const recent = projection.items
+            .filter((item) => (usage.get(item.refKey)?.count ?? 0) > 0)
+            .sort((a, b) => heat(a, b) || fallback(a, b))
+            .slice(0, 10);
+        const keys = new Set(recent.map((item) => item.refKey));
+        return [
+            ...recent.map((item) => ({ ...item, section: 'recent' })),
+            ...projection.items
+                .filter((item) => !keys.has(item.refKey))
+                .sort(fallback)
+                .map((item) => ({ ...item, section: 'kind' })),
+        ];
+    }
+    const matches = projection.items.map((item) => match(item, query));
+    const strictCount = matches.filter((item) => item.tier < 3).length;
+    return matches
+        .filter((m) => m.tier < 3 || (strictCount < 12 && m.score >= 0.42))
+        .sort((a, b) => a.tier - b.tier ||
+        b.score - a.score ||
+        a.field - b.field ||
+        heat(a.item, b.item) ||
+        compareText(a.item.refKey, b.item.refKey))
+        .map((m) => ({ ...m.item, section: m.tier === 3 ? 'fuzzy' : 'strict' }));
+}