@chengxianglibra/dsh-data-analysis 0.1.1 → 0.2.0

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

@@ -0,0 +1,255 @@
+/** 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: 3;
+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 type PresentationLocale = 'zh-CN' | 'en-US';
+export interface PresentationDraft {
+    schemaVersion: 2;
+    locale: PresentationLocale;
+    title: string;
+    datasets: DraftDataset[];
+    sources: DeclaredSource[];
+    blocks: PresentationBlock[];
+    interaction?: PresentationInteraction;
+}
+export interface PresentationDiagnostic {
+    code: string;
+    path: string;
+    message: string;
+}
+export interface PresentationDocument {
+    schemaVersion: 3;
+    locale: PresentationLocale;
+    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): () => Promise<void>;

package/lib/types/presentation/export-html.d.ts

@@ -0,0 +1,13 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+export declare const MARIVO_EXPORT_HTML_TOOL_NAME = "marivo_export_html";
+export type ExportWorkspaceSource = () => {
+    id: string;
+    path: string;
+} | Promise<{
+    id: string;
+    path: string;
+}>;
+export declare function parseHtmlOutputPath(value: unknown): string;
+export declare function createMarivoExportHtmlTool(source: ExportWorkspaceSource, session: Session): import("@deepseek-ai/dsh-tools").ToolDefinition;
+export declare function registerMarivoExportHtmlTool(ctx: Context, source: ExportWorkspaceSource, session: Session): () => Promise<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,10 @@
+import { type PublicationSource, type ReportCatalog, type ReportHistory } from './contracts/catalog.ts';
+import { type PresentationDocument, type PresentationReceipt } from './contracts/index.ts';
+export declare function readReceiptDocument(root: string, receipt: PresentationReceipt, signal?: AbortSignal): Promise<PresentationDocument>;
+/** Current and its publication history become visible through one atomic rename. */
+export declare function readReportHistory(root: string, workspaceId: string, reportId: string, signal?: AbortSignal): Promise<ReportHistory>;
+export declare function resolvePresentation(root: string, workspaceId: string, reportId: string, signal?: AbortSignal): Promise<PresentationReceipt>;
+/** Enumerate only publication pointers, never completed-but-unpublished build directories. */
+export declare function listReports(root: string, workspaceId: string, signal?: AbortSignal): Promise<ReportCatalog>;
+/** 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, source?: PublicationSource | null): Promise<PresentationReceipt>;

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

@@ -0,0 +1,25 @@
+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, resolveId?: PresentationWorkspaceResolver);
+    catalog(endpoint: 'reports/list' | 'reports/history', payload: unknown, caller?: AbortSignal): Promise<import("./contracts/catalog.ts").ReportHistory | import("./contracts/catalog.ts").ReportCatalog>;
+    close(): Promise<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 the document, 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): () => Promise<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/report-publishing/adapters.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { HostConnectionHandle } from '@deepseek-ai/dsh-client-connection';
+import type { ReportPublishingService } from './service.ts';
+export declare const PUBLISHING_CHANNEL = "/dsh-report-publishing";
+export declare function registerPublishingCredentials(connection: HostConnectionHandle, service: ReportPublishingService, workspaceExists: (id: string) => boolean): () => Promise<void>;
+export declare function registerReportPublishTool(ctx: Context, service: ReportPublishingService, sessionId: string): () => Promise<void>;

package/lib/types/report-publishing/config.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+export declare const publishingConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    storage: z.ZodObject<{
+        name: z.ZodString;
+        protocol: z.ZodDefault<z.ZodLiteral<"s3">>;
+        endpoint: z.ZodString;
+        region: z.ZodString;
+        bucket: z.ZodString;
+        forcePathStyle: z.ZodDefault<z.ZodBoolean>;
+        accessKeyIdRef: z.ZodString;
+        secretAccessKeyRef: z.ZodString;
+        sessionTokenRef: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    pathPrefix: z.ZodDefault<z.ZodString>;
+    publicBaseUrl: z.ZodString;
+}, z.core.$strict>;
+export type ReportPublishingConfig = z.input<typeof publishingConfigSchema> | {
+    enabled?: false;
+};
+export type EnabledPublishingConfig = z.output<typeof publishingConfigSchema>;
+export declare function resolvePublishingConfig(value?: ReportPublishingConfig): EnabledPublishingConfig | undefined;

package/lib/types/report-publishing/service.d.ts

@@ -0,0 +1,68 @@
+import { type CredentialProvider } from '@deepseek-ai/dsh-credentials';
+import type { MarivoPresentationFileService } from '../presentation/rpc.ts';
+import type { EnabledPublishingConfig } from './config.ts';
+export declare function publishingPathName(value: string, fallback: string): string;
+export type PublishingField = 'accessKeyId' | 'secretAccessKey' | 'sessionToken';
+export interface PublishingCredentialField {
+    field: PublishingField;
+    reference: string;
+    required: boolean;
+    configured: boolean;
+    writable: boolean;
+    source?: string;
+}
+export interface PublishingCredentialView {
+    enabled: boolean;
+    configId?: string;
+    name?: string;
+    bucket?: string;
+    fields: PublishingCredentialField[];
+}
+type Store = Pick<CredentialProvider, 'describe' | 'set' | 'unset' | 'resolve'>;
+export interface UploadInput {
+    config: EnabledPublishingConfig;
+    credentials: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
+    key: string;
+    bytes: Buffer;
+    signal: AbortSignal;
+}
+export declare function uploadReport(input: UploadInput): Promise<void>;
+export declare class ReportPublishingService {
+    readonly configId: `${string}-${string}-${string}-${string}-${string}`;
+    readonly config: EnabledPublishingConfig | undefined;
+    readonly store: Store;
+    readonly files: Pick<MarivoPresentationFileService, 'catalog' | 'read'>;
+    readonly upload: (input: UploadInput) => Promise<void>;
+    readonly workspaceName: (id: string) => string;
+    constructor(config: EnabledPublishingConfig | undefined, store: Store, files: Pick<MarivoPresentationFileService, 'catalog' | 'read'>, upload?: (input: UploadInput) => Promise<void>, workspaceName?: (id: string) => string);
+    assertConfig(configId: string): void;
+    references(): Array<{
+        field: PublishingField;
+        reference: string;
+        required: boolean;
+    }>;
+    describe(): Promise<PublishingCredentialView>;
+    change(field: PublishingField, value: string | undefined, signal: AbortSignal): Promise<void>;
+    publish(scope: {
+        sessionId: string;
+    } | {
+        workspaceId: string;
+    }, reportId: string, buildId: string, signal: AbortSignal, viewHtml?: string): Promise<{
+        storage: string;
+        bucket: string;
+        key: string;
+        url: string;
+        workspaceId: string;
+        reportId: string;
+        buildId: string;
+        sha256: string;
+        bytes: number;
+        kind: string;
+        publishedAt: string;
+    }>;
+}
+export {};

package/lib/types/rpc.d.ts

@@ -0,0 +1,3 @@
+/** Dedicated plugin RPC envelopes over Harness-owned authenticated exact Fetch routes. */
+import { type ConnectionRpcHandler, type HostConnectionHandle } from '@deepseek-ai/dsh-client-connection';
+export declare function registerPluginRpc(connection: Pick<HostConnectionHandle, 'fetch'>, channel: string, endpoints: readonly string[], handler: ConnectionRpcHandler): () => Promise<void>;

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

@@ -0,0 +1,47 @@
+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 declare const CATALOG_ERROR_SCHEMA = "marivo.semantic_catalog_error/v1";
+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 CatalogFailure {
+    readonly schema: typeof CATALOG_ERROR_SCHEMA;
+    readonly kind: 'semantic';
+    readonly message: string;
+}
+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 parseCatalogFailure(value: unknown): CatalogFailure | undefined;
+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,26 @@
+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>;
+}
+export declare class SemanticCatalogLoadError extends Error {
+    readonly code = "catalog-load-failed";
+    readonly diagnostic: string;
+    constructor(diagnostic: string);
+}
+/** 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>;
+    close(): Promise<void>;
+    dispose(): void;
+}
+/** Preserve Marivo semantic diagnostics; keep unknown Python failures behind a fixed fallback. */
+export declare function browserFailure(error: unknown): string;

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

@@ -0,0 +1,12 @@
+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>;
+    close(): Promise<void>;
+    invalidate(key: string): void;
+    dispose(): void;
+}