@chengxianglibra/dsh-data-analysis 0.1.1 → 0.1.2

package/lib/types/presentation/contracts/editing.d.ts

@@ -0,0 +1,8 @@
+import type { PresentationBlock, PresentationDocument } from './types.ts';
+export interface PresentationEdits {
+    title: string;
+    blocks: PresentationBlock[];
+}
+export declare function presentationEdits(document: PresentationDocument): PresentationEdits;
+/** Only presentation fields are accepted. Saved data, sources and captured code stay server-owned. */
+export declare function applyPresentationEdits(base: PresentationDocument, value: unknown): PresentationDocument;

package/lib/types/presentation/contracts/index.d.ts

@@ -0,0 +1,11 @@
+import { type Cell, type DatasetColumn, type PresentationDocument, type PresentationDraft, type PresentationReceipt, type TypedDataset } from './types.ts';
+export * from './charts.ts';
+export * from './types.ts';
+export * from './values.ts';
+export declare function parsePresentationBuildId(value: unknown, path?: string): string;
+export declare function parseTypedDataset(value: unknown, path?: string): TypedDataset;
+/** Tables retain the original decimal/int64 spelling, including trailing decimal zeroes. */
+export declare function formatCell(value: Cell, _column: DatasetColumn): string;
+export declare function parsePresentationDraft(value: unknown): PresentationDraft;
+export declare function parsePresentationDocument(value: unknown): PresentationDocument;
+export declare function parsePresentationReceipt(value: unknown): PresentationReceipt;

package/lib/types/presentation/contracts/interaction.d.ts

@@ -0,0 +1,8 @@
+import type { PresentationBlock, PresentationDocument, PresentationInteraction } from './types.ts';
+export declare function defaultSelection(interaction: PresentationInteraction): Record<string, string>;
+export declare function selectedSlice(interaction: PresentationInteraction, selection: Record<string, string>): import("./types.ts").PresentationSlice;
+export declare function interactionRows(interaction: PresentationInteraction | undefined, selection: Record<string, string>, block: PresentationBlock): number[] | undefined;
+export declare function filterSummary(interaction: PresentationInteraction, selection: Record<string, string>): string;
+/** Preserve the authored before / interactive / after boundary during host edits. */
+export declare function blockRegion(document: PresentationDocument, id: string): number;
+export declare function editedInteraction(document: PresentationDocument, blocks: PresentationBlock[]): PresentationInteraction | undefined;

package/lib/types/presentation/contracts/types.d.ts

@@ -0,0 +1,252 @@
+/** Pure presentation data. No Marivo schema, Node runtime or Host imports. */
+import type { PythonCodeRef, PythonCodeSnippet } from '../../python-execution-contracts.ts';
+export type { PythonCodeRef, PythonCodeSnippet } from '../../python-execution-contracts.ts';
+export declare const PRESENTATION_SCHEMA_VERSION: 2;
+export declare const PRESENTATION_BUDGETS: {
+    readonly documentBytes: number;
+    readonly draftBytes: number;
+    readonly datasetBytes: number;
+    readonly htmlBytes: number;
+    readonly datasets: 16;
+    readonly columns: 64;
+    readonly rows: 5000;
+    readonly cells: 100000;
+    readonly sources: 64;
+    readonly codeSnippets: 32;
+    readonly blocks: 64;
+    readonly text: 32768;
+};
+export type ColumnType = 'string' | 'boolean' | 'float64' | 'int64' | 'decimal' | 'date' | 'datetime';
+export type Cell = string | boolean | number | null;
+export interface DatasetColumn {
+    id: string;
+    label: string;
+    type: ColumnType;
+    nullable: boolean;
+    unit?: string;
+}
+/** int64/decimal are exact strings; datetime always includes an explicit offset. */
+export interface TypedDataset {
+    schemaVersion: 1;
+    columns: DatasetColumn[];
+    rows: Cell[][];
+    rowCount: number;
+    limit: number;
+    truncated: boolean;
+}
+export interface SourceRef {
+    sessionId: string;
+    artifactRef: string;
+    findingId?: string;
+}
+export interface DeclaredSource {
+    id: string;
+    ref: SourceRef;
+}
+/** Captured SQL belongs to an exact persisted producer, never a reconstructed query. */
+export interface SqlCodeSnippet {
+    language: 'sql';
+    text: string;
+    provenance: 'execution';
+    runId: string;
+    queryId: string;
+    artifactRef: string;
+}
+export interface SourceCodeSnapshot {
+    snippets: SqlCodeSnippet[];
+    notices: string[];
+}
+export type SourceSnapshot = DeclaredSource & ({
+    status: 'available';
+    label: string;
+    facts: {
+        label: string;
+        value: string;
+    }[];
+    code?: SourceCodeSnapshot;
+} | {
+    status: 'unavailable';
+    reason: string;
+});
+export type DraftDataset = ({
+    id: string;
+    kind: 'artifact';
+    sourceId: string;
+    columns?: string[];
+    rowLimit: number;
+} | {
+    id: string;
+    kind: 'computed';
+    path: string;
+    sourceIds: string[];
+}) & {
+    codeRefs?: PythonCodeRef[];
+};
+export interface DocumentDataset {
+    id: string;
+    origin: 'artifact' | 'computed';
+    data: TypedDataset;
+    sourceIds: string[];
+    code?: PythonCodeSnippet[];
+}
+export type ChartType = 'line' | 'area' | 'stackedArea' | 'sparkline' | 'bar' | 'horizontalBar' | 'stackedBar' | 'stackedBar100' | 'horizontalStackedBar' | 'horizontalStackedBar100' | 'histogram' | 'boxPlot' | 'scatter' | 'heatmap' | 'pie' | 'leaderboard' | 'funnel' | 'waterfall';
+/** Names identify columns containing prepared values, never expressions or statistics. */
+export interface ChartBindings {
+    binStart?: string;
+    binEnd?: string;
+    minimum?: string;
+    q1?: string;
+    q3?: string;
+    maximum?: string;
+    start?: string;
+    end?: string;
+    role?: string;
+    share?: string;
+    rank?: string;
+    denominator?: string;
+    size?: string;
+    label?: string;
+    color?: string;
+}
+export interface ChartOptions {
+    showPoints?: 'auto' | 'always' | 'never';
+    series?: Record<string, {
+        lineStyle?: 'solid' | 'dashed' | 'dotted';
+        role?: 'actual' | 'baseline' | 'target' | 'forecast' | 'plan' | 'comparison';
+    }>;
+    valueLabels?: 'none' | 'auto' | 'all';
+    referenceLines?: {
+        axis: 'x' | 'y';
+        value: number;
+        label?: string;
+    }[];
+}
+interface ChartViewFields {
+    datasetId: string;
+    x: string;
+    y: string[];
+    numericMode: 'exact' | 'approximate';
+    bindings?: ChartBindings;
+    options?: ChartOptions;
+}
+type PreparedChart<Type extends ChartType, Keys extends keyof ChartBindings> = {
+    chart: Type;
+    bindings: ChartBindings & Required<Pick<ChartBindings, Keys>>;
+};
+/** Statistical families require prepared bindings at both the type and JSON boundaries. */
+export type ChartView = ChartViewFields & ({
+    chart: Exclude<ChartType, 'histogram' | 'boxPlot' | 'waterfall' | 'pie' | 'funnel' | 'leaderboard' | 'stackedBar100' | 'horizontalStackedBar100'>;
+} | PreparedChart<'histogram', 'binStart' | 'binEnd'> | PreparedChart<'boxPlot', 'minimum' | 'q1' | 'q3' | 'maximum'> | PreparedChart<'waterfall', 'start' | 'end' | 'role'> | PreparedChart<'pie' | 'funnel', 'share'> | PreparedChart<'leaderboard', 'rank'> | PreparedChart<'stackedBar100' | 'horizontalStackedBar100', 'denominator'>);
+/** Prepared values in the metric's selected row; no reader-side calculations. */
+export interface MetricComparison {
+    label: string;
+    referenceColumnId?: string;
+    deltaColumnId?: string;
+    relativeColumnId?: string;
+    sentiment?: 'higher-is-better' | 'lower-is-better' | 'neutral';
+}
+export type PresentationBlock = {
+    id: string;
+    kind: 'markdown';
+    text: string;
+} | ({
+    id: string;
+    kind: 'metric';
+    datasetId: string;
+    columnId: string;
+    label: string;
+    description?: string;
+    comparisons?: MetricComparison[];
+} & ({
+    rowIndex: number;
+    rowSelection?: never;
+} | {
+    rowSelection: 'slice';
+    rowIndex?: never;
+})) | ({
+    id: string;
+    kind: 'chart';
+    preparedViews?: (ChartView & {
+        id: string;
+        label: string;
+    })[];
+} & ChartView) | {
+    id: string;
+    kind: 'table';
+    datasetId: string;
+    columns?: string[];
+} | {
+    id: string;
+    kind: 'source';
+    sourceIds: string[];
+};
+/** Author-prepared combinations; the reader never computes business aggregates. */
+export interface PresentationFilter {
+    id: string;
+    label: string;
+    allOptionId: string;
+    options: {
+        id: string;
+        label: string;
+    }[];
+}
+export interface PresentationSlice {
+    selection: Record<string, string>;
+    datasets: {
+        datasetId: string;
+        rowIndices: number[];
+    }[];
+}
+export interface PresentationInteraction {
+    title: string;
+    blockIds: string[];
+    filters: PresentationFilter[];
+    slices: PresentationSlice[];
+}
+export interface PresentationDraft {
+    schemaVersion: 1;
+    title: string;
+    datasets: DraftDataset[];
+    sources: DeclaredSource[];
+    blocks: PresentationBlock[];
+    interaction?: PresentationInteraction;
+}
+export interface PresentationDiagnostic {
+    code: string;
+    path: string;
+    message: string;
+}
+export interface PresentationDocument {
+    schemaVersion: 2;
+    reportId: string;
+    workspaceId: string;
+    buildId: string;
+    title: string;
+    generatedAt: string;
+    datasets: DocumentDataset[];
+    sources: SourceSnapshot[];
+    blocks: PresentationBlock[];
+    diagnostics: PresentationDiagnostic[];
+    interaction?: PresentationInteraction;
+}
+export type PresentationAsset = 'presentation.json' | 'index.html';
+export interface PresentationFile<Asset extends PresentationAsset = PresentationAsset> {
+    asset: Asset;
+    path: string;
+    sha256: string;
+    bytes: number;
+}
+/** Session and Turn belong to the Host delivery envelope, not to the file identity. */
+export interface PresentationReceipt {
+    schemaVersion: 2;
+    reportId: string;
+    kind: 'marivo.presentation';
+    workspaceId: string;
+    buildId: string;
+    title: string;
+    summary: string;
+    files: {
+        document: PresentationFile<'presentation.json'>;
+        html: PresentationFile<'index.html'>;
+    };
+}

package/lib/types/presentation/contracts/values.d.ts

@@ -0,0 +1,9 @@
+import type { Cell, DatasetColumn } from './types.ts';
+export declare class PresentationContractError extends Error {
+    readonly code: string;
+    readonly path: string;
+    readonly hint: string;
+    readonly reason: string;
+    constructor(code: string, path: string, message: string, hint?: string);
+}
+export declare function chartNumber(value: Cell, column: DatasetColumn, mode: 'exact' | 'approximate', path?: string): number | null;

package/lib/types/presentation/delivery.d.ts

@@ -0,0 +1,3 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** Persist the same envelope on nested Code dispatch even when code discards the return value. */
+export declare function installMarivoPresentationCodeDelivery(ctx: Context): () => void;

package/lib/types/presentation/files.d.ts

@@ -0,0 +1,7 @@
+import { type PresentationAsset } from './contracts/index.ts';
+export declare function presentationReportPath(root: string, reportId: string): string;
+export declare function presentationAssetPath(root: string, reportId: string, buildId: string, asset: PresentationAsset): string;
+export declare function presentationSha256(bytes: Uint8Array): string;
+/** Bounded raw-byte reader with no symbolic links and stable directory/file identity. */
+export declare function readPresentationAsset(workspaceRoot: string, reportId: string, buildId: string, asset: PresentationAsset, signal?: AbortSignal): Promise<Buffer>;
+export declare function readReportFile(workspaceRoot: string, filename: string, maximum: number, signal?: AbortSignal): Promise<Buffer>;

package/lib/types/presentation/index.d.ts

@@ -0,0 +1,6 @@
+export * from './contracts/index.ts';
+export * from './delivery.ts';
+export * from './projection/index.ts';
+export * from './receipt.ts';
+export * from './rpc.ts';
+export * from './tool.ts';

package/lib/types/presentation/lint.d.ts

@@ -0,0 +1,13 @@
+/** Static preflight only: never starts a Runtime or publishes presentation assets. */
+export declare function lintPresentationDraft(workspaceRoot: string, draftPath: string): Promise<{
+    ok: boolean;
+    scope: string;
+    checkedComputedDatasets: number;
+    diagnostics: {
+        code: string;
+        path: string;
+        message: string;
+        hint: string;
+    }[];
+    deferredChecks: string[];
+}>;

package/lib/types/presentation/projection/files.d.ts

@@ -0,0 +1,2 @@
+/** Read raw bytes under a strict budget before JSON parsing, including concurrent growth. */
+export declare function readWorkspaceJson(workspaceRoot: string, relativePath: string, maximum: number, location: string, signal?: AbortSignal): Promise<unknown>;

package/lib/types/presentation/projection/index.d.ts

@@ -0,0 +1,20 @@
+import type { MarivoCheckedRunner } from '../../environment/types.ts';
+import { type PresentationDocument, type PresentationDraft } from '../contracts/index.ts';
+export { readWorkspaceJson } from './files.ts';
+export interface PresentationProjectionOptions {
+    /** Workspace identity is resolved by Host together with this runner, never from a draft. */
+    workspaceId: string;
+    reportId: string;
+    buildId: string;
+    generatedAt?: string;
+    signal?: AbortSignal;
+}
+/** Internal S2 bridge: restores public data without observe, revalidation or credential admission. */
+export declare class MarivoPresentationProjection {
+    #private;
+    constructor(runner: MarivoCheckedRunner);
+    get status(): "ready" | "failed";
+    get binding(): Readonly<import("../../environment/types.ts").MarivoEnvironmentBinding>;
+    readDraft(relativePath: string, signal?: AbortSignal): Promise<PresentationDraft>;
+    project(value: unknown, options: PresentationProjectionOptions): Promise<PresentationDocument>;
+}

package/lib/types/presentation/projection/program.d.ts

@@ -0,0 +1,2 @@
+/** Fixed public read program. Drafts contain references and data paths, never executable code. */
+export declare const MARIVO_PRESENTATION_READ_PROGRAM: string;

package/lib/types/presentation/projection/sql-code.d.ts

@@ -0,0 +1,2 @@
+/** Only persisted public producer records are read; this program never compiles or executes SQL. */
+export declare const MARIVO_PRESENTATION_SQL_CODE_PROGRAM: string;

package/lib/types/presentation/receipt.d.ts

@@ -0,0 +1,14 @@
+/** Pure Host delivery envelope shared by the server and browser. */
+import { type PresentationReceipt } from './contracts/index.ts';
+export declare const MARIVO_PRESENT_TOOL_NAME = "marivo_present";
+export declare const MARIVO_PRESENTATION_DELIVERY_KIND = "marivo.presentation.delivery";
+export declare const MARIVO_PRESENTATION_RPC_CHANNEL = "/marivo-presentation";
+export interface PresentationDelivery {
+    kind: typeof MARIVO_PRESENTATION_DELIVERY_KIND;
+    schemaVersion: 2;
+    dshSessionId: string;
+    turn: number;
+    receipt: PresentationReceipt;
+}
+export declare function parsePresentationDelivery(value: unknown): PresentationDelivery;
+export declare function presentationReceiptText(receipt: PresentationReceipt): string;

package/lib/types/presentation/reports.d.ts

@@ -0,0 +1,5 @@
+import { type PresentationDocument, type PresentationReceipt } from './contracts/index.ts';
+export declare function readReceiptDocument(root: string, receipt: PresentationReceipt, signal?: AbortSignal): Promise<PresentationDocument>;
+export declare function resolvePresentation(root: string, workspaceId: string, reportId: string, signal?: AbortSignal): Promise<PresentationReceipt>;
+/** The mutable pointer is the publication boundary; completed builds are never overwritten. */
+export declare function publishPresentation(root: string, document: PresentationDocument, expectedBuildId: string | null, assertOwner: () => Promise<void>, signal?: AbortSignal): Promise<PresentationReceipt>;

package/lib/types/presentation/rpc.d.ts

@@ -0,0 +1,24 @@
+import type { HostConnectionHandle } from '@deepseek-ai/dsh-client-connection';
+import { type PresentationAsset } from './contracts/index.ts';
+export interface PresentationWorkspace {
+    id: string;
+    path: string;
+}
+export type PresentationWorkspaceResolver = (sessionId: string) => PresentationWorkspace | undefined | Promise<PresentationWorkspace | undefined>;
+export declare class MarivoPresentationFileService {
+    #private;
+    constructor(resolve: PresentationWorkspaceResolver);
+    close(): void;
+    report(endpoint: 'reports/resolve' | 'reports/save', payload: unknown, caller?: AbortSignal): Promise<import("./contracts/types.ts").PresentationReceipt>;
+    read(payload: unknown, caller?: AbortSignal): Promise<{
+        workspaceId: string;
+        reportId: string;
+        buildId: string;
+        asset: PresentationAsset;
+        mimeType: string;
+        sha256: string;
+        bytes: number;
+        bodyBase64: string;
+    }>;
+}
+export declare function registerMarivoPresentationRpc(connection: HostConnectionHandle, service: MarivoPresentationFileService): () => Promise<void>;

package/lib/types/presentation/tool.d.ts

@@ -0,0 +1,12 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { MarivoPresentationProjection } from './projection/index.ts';
+export interface PresentationBinding {
+    workspaceId: string;
+    projection: MarivoPresentationProjection;
+}
+export type PresentationBindingSource = () => PresentationBinding | Promise<PresentationBinding>;
+/** One call projects a draft, builds both assets, commits them, then emits the receipt. */
+export declare function createMarivoPresentTool(source: PresentationBindingSource, session: Session, lifecycleSignal?: AbortSignal): ToolDefinition;
+export declare function registerMarivoPresentTool(ctx: Context, source: PresentationBindingSource, session: Session): () => void;

package/lib/types/python-execution-contracts.d.ts

@@ -0,0 +1,10 @@
+/** Host-issued reference to an immutable successful Python execution snapshot. */
+export interface PythonCodeRef {
+    executionId: string;
+    sha256: string;
+}
+export interface PythonCodeSnippet extends PythonCodeRef {
+    language: 'python';
+    text: string;
+    provenance: 'execution';
+}

package/lib/types/python-execution.d.ts

@@ -0,0 +1,10 @@
+import type { PythonCodeRef, PythonCodeSnippet } from './python-execution-contracts.ts';
+export type { PythonCodeRef, PythonCodeSnippet } from './python-execution-contracts.ts';
+/** Publish a complete record once. Its final name never exposes a partial write or overwrites. */
+export declare function savePythonExecution(workspaceRoot: string, input: {
+    text: string;
+    startedAt: string;
+    finishedAt: string;
+}, signal?: AbortSignal): Promise<PythonCodeRef>;
+/** Resolve Host-stored execution identities for the bound Workspace. Never executes code. */
+export declare function readPythonExecution(workspaceRoot: string, ref: PythonCodeRef, signal?: AbortSignal): Promise<PythonCodeSnippet>;

package/lib/types/semantic-browser/contracts.d.ts

@@ -0,0 +1,40 @@
+import { type SemanticRef } from '../semantic-reference/contracts.ts';
+import { type ComputationDefinition } from './definition.ts';
+export declare const BROWSER_ENDPOINT = "semantic-browser/catalog";
+export declare const CATALOG_MAX_BYTES: number;
+export interface DisplayField {
+    readonly name: string;
+    readonly value: string;
+}
+export interface ObjectRelation {
+    readonly field: string;
+    readonly ref: SemanticRef;
+}
+export interface SemanticObjectView {
+    readonly ref: SemanticRef;
+    readonly computation: ComputationDefinition | null;
+    readonly name: string;
+    readonly domain: string | null;
+    readonly definition: string | null;
+    readonly guardrails: readonly string[];
+    readonly source: {
+        readonly file: string;
+        readonly line: number;
+        readonly symbol: string;
+    };
+    readonly fields: readonly DisplayField[];
+    readonly relations: readonly ObjectRelation[];
+}
+export interface CatalogProjection {
+    readonly fingerprint: string;
+    readonly kinds: readonly string[];
+    readonly objects: readonly SemanticObjectView[];
+}
+export interface CatalogSnapshot extends CatalogProjection {
+    readonly workspaceId: string;
+    readonly projectRoot: string;
+    readonly environmentFingerprint: string;
+    readonly loadedAt: string;
+}
+export declare function parseCatalogProjection(value: unknown): CatalogProjection;
+export declare function parseCatalogSnapshot(value: unknown): CatalogSnapshot;

package/lib/types/semantic-browser/definition.d.ts

@@ -0,0 +1,20 @@
+import { type SemanticRef } from '../semantic-reference/contracts.ts';
+export type DefinitionValue = string | number | boolean | null | DefinitionValue[] | {
+    readonly [key: string]: DefinitionValue;
+};
+export interface ComputationDefinition {
+    readonly schema: 'marivo.semantic_definition/v1';
+    readonly ref: SemanticRef;
+    readonly catalog_definition_fingerprint: string;
+    readonly node: {
+        readonly [key: string]: DefinitionValue;
+    };
+    readonly temporal: {
+        readonly [key: string]: DefinitionValue;
+    };
+    readonly source_location: {
+        readonly file: string;
+        readonly line: number;
+    };
+}
+export declare function parseComputation(input: unknown, ref: SemanticRef, fingerprint: string): ComputationDefinition | null;

package/lib/types/semantic-browser/program.d.ts

@@ -0,0 +1,2 @@
+/** Explicit public Details projection. No object dump, source-code read or data operation. */
+export declare const BROWSER_CATALOG_PROGRAM: string;

package/lib/types/semantic-browser/service.d.ts

@@ -0,0 +1,20 @@
+import type { MarivoCheckedRunner } from '../environment/types.ts';
+import { type CatalogSnapshot } from './contracts.ts';
+export interface BrowserWorkspace {
+    readonly id: string;
+    readonly path: string;
+}
+export interface BrowserHost {
+    getWorkspace(id: string): BrowserWorkspace | undefined;
+    projectRoot(workspace: BrowserWorkspace): string;
+    resolve(root: string): Promise<MarivoCheckedRunner>;
+}
+/** Workspace-addressed read service; intentionally has no Agent or credential dependency. */
+export declare class SemanticBrowserService {
+    #private;
+    constructor(host: BrowserHost);
+    read(payload: unknown, caller: AbortSignal): Promise<CatalogSnapshot>;
+    dispose(): void;
+}
+/** Fixed diagnostics only: Python errors may contain model code or datasource secrets. */
+export declare function browserFailure(error: unknown): string;

package/lib/types/semantic-reference/bridge.d.ts

@@ -0,0 +1,11 @@
+import type { MarivoCheckedRunner } from '../environment/types.ts';
+import { type Projection } from './contracts.ts';
+export declare const CATALOG_PROGRAM: string;
+/** One plugin-owned cache, keyed by the exact Environment fingerprint. */
+export declare class SemanticReferenceBridge {
+    #private;
+    constructor(clock?: () => number);
+    candidates(runner: MarivoCheckedRunner, signal: AbortSignal): Promise<Projection>;
+    invalidate(key: string): void;
+    dispose(): void;
+}

package/lib/types/semantic-reference/contracts.d.ts

@@ -0,0 +1,51 @@
+/** Browser-safe wire contracts. These bounds do not reimplement Marivo's domain grammar. */
+export declare const CHANNEL = "/dsh-data-analysis";
+export declare const SOURCE = "marivo-semantic";
+export declare const LIMIT = 40;
+export declare const MAX_WIRE_BYTES: number;
+export interface SemanticRef {
+    readonly schema: 'marivo.semantic_ref/v1';
+    readonly kind: string;
+    readonly path: string;
+}
+export interface Envelope {
+    readonly schema: 'dsh-data-analysis-semantic-reference/v1';
+    readonly sessionId: string;
+    readonly environmentFingerprint: string;
+    readonly ref: SemanticRef;
+}
+export interface Candidate {
+    readonly ref: SemanticRef;
+    readonly refKey: string;
+    readonly name: string;
+    readonly businessDefinition: string | null;
+}
+export interface Projection {
+    readonly kinds: readonly string[];
+    readonly items: readonly Candidate[];
+}
+export interface RankedCandidate extends Candidate {
+    readonly section: 'recent' | 'kind' | 'strict' | 'fuzzy';
+}
+export interface CandidatesResponse {
+    readonly environmentFingerprint: string;
+    readonly items: readonly RankedCandidate[];
+}
+export declare function closed(value: unknown, keys: readonly string[]): Record<string, unknown>;
+export declare function boundedText(value: unknown, max: number, empty?: boolean): string;
+export declare function parseJson(value: unknown, max?: number): unknown;
+export declare function parseRef(value: unknown): SemanticRef;
+export declare function refKey(ref: SemanticRef): string;
+export declare function parseEnvelope(value: unknown): Envelope;
+export declare function envelopeJson(envelope: Envelope): string;
+export declare function modelMarker(envelope: Envelope): string;
+export declare function parseCandidate(value: unknown): Candidate;
+export declare function parseProjection(value: unknown): Projection;
+export declare function parseCandidatesRequest(value: unknown): {
+    version: number;
+    sessionId: string;
+    query: string;
+    quoted: boolean;
+    limit: number;
+};
+export declare function parseCandidatesResponse(value: unknown): CandidatesResponse;

package/lib/types/semantic-reference/index.d.ts

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

package/lib/types/semantic-reference/rpc.d.ts

@@ -0,0 +1,15 @@
+import type { ConnectionRpcHandler, HostConnectionHandle } from '@deepseek-ai/dsh-client-connection';
+import type { MarivoCheckedRunner } from '../environment/types.ts';
+import { SemanticReferenceBridge } from './bridge.ts';
+import { type SemanticReferenceUsage } from './usage.ts';
+export type EnvironmentResolver = (sessionId: string, purpose: 'candidates' | 'reference') => Promise<MarivoCheckedRunner>;
+/** Abort the caller's wait, without pretending to cancel the shared Environment resolver. */
+export declare function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T>;
+export declare class SemanticReferenceService {
+    #private;
+    constructor(resolve: EnvironmentResolver, usage: SemanticReferenceUsage, bridge?: SemanticReferenceBridge);
+    handle(endpoint: string, payload: unknown, caller: AbortSignal): Promise<unknown>;
+    stop(): void;
+    close(): Promise<void>;
+}
+export declare function registerSemanticReferenceRpc(connection: HostConnectionHandle, service: SemanticReferenceService, browser?: ConnectionRpcHandler): () => Promise<void>;

package/lib/types/semantic-reference/search.d.ts

@@ -0,0 +1,10 @@
+import { type Projection, type RankedCandidate } from './contracts.ts';
+export interface UsageScore {
+    readonly count: number;
+    readonly last: number;
+}
+export type UsageScores = ReadonlyMap<string, UsageScore>;
+export declare function normalize(text: string): string;
+export declare function compareText(a: string, b: string): number;
+export declare function dice(a: string, b: string): number;
+export declare function search(projection: Projection, rawQuery: string, usage?: UsageScores): readonly RankedCandidate[];