@chengxianglibra/dsh-data-analysis 0.1.1 → 0.1.2

package/lib/presentation/projection/program.js

@@ -0,0 +1,144 @@
+import { MARIVO_PRESENTATION_SQL_CODE_PROGRAM } from "./sql-code.js";
+/** Fixed public read program. Drafts contain references and data paths, never executable code. */
+export const MARIVO_PRESENTATION_READ_PROGRAM = String.raw `
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+import marivo.analysis as mv
+import marivo.datasource as md
+from dsh_data_analysis_presentation._dataset import encode_dataset
+
+
+class ProjectionFailure(Exception):
+    def __init__(self, code, path, message):
+        self.code, self.path, self.message = code, path, message
+
+
+class DenyCredentials:
+    def resolve(self, request):
+        raise ProjectionFailure("credential_read_forbidden", "/sources", "Persisted presentation reads cannot obtain datasource credentials.")
+
+
+def text(value, limit=32768):
+    result = value if isinstance(value, str) else json.dumps(value, ensure_ascii=False, allow_nan=False, separators=(",", ":"))
+    result = result.replace("\0", "\\u0000")
+    return result if len(result) <= limit else result[:limit - 14] + " [truncated]"
+
+
+${MARIVO_PRESENTATION_SQL_CODE_PROGRAM}
+
+
+def read(request):
+    sessions, artifacts, contracts = {}, {}, {}
+    sources, datasets, diagnostics = [], [], []
+    definition_sources = []
+    read_at = datetime.now(timezone.utc).isoformat()
+    try:
+        for index, declared in enumerate(request["sources"]):
+            ref = declared["ref"]
+            source_path = "/sources/" + str(index)
+            try:
+                session = sessions.get(ref["sessionId"])
+                if session is None:
+                    session = mv.session.resume(ref["sessionId"], use_datasources=False)
+                    sessions[ref["sessionId"]] = session
+                if session.id != ref["sessionId"]:
+                    raise ProjectionFailure("source_identity_mismatch", source_path + "/ref/sessionId", "Restored Session identity differs from the declared source.")
+                artifact = session.artifact(ref["artifactRef"])
+                contract = artifact.contract()
+                meta = artifact.meta
+                if artifact.ref != ref["artifactRef"] or meta.session_id != session.id or contract.ref != artifact.ref:
+                    raise ProjectionFailure("source_identity_mismatch", source_path + "/ref", "Restored Artifact identity differs from the declared source.")
+                if Path(meta.project_root).resolve() != Path.cwd().resolve():
+                    raise ProjectionFailure("source_workspace_mismatch", source_path + "/ref", "Restored Artifact belongs to a different Workspace.")
+            except ProjectionFailure:
+                raise
+            except Exception:
+                # Only the requested source becomes unavailable. Exception messages may
+                # include credentials, project paths or raw SQL and are never returned.
+                sources.append({**declared, "status": "unavailable", "reason": "The declared Artifact cannot be restored through the bound Workspace public API."})
+                continue
+
+            artifacts[declared["id"]], contracts[declared["id"]] = artifact, contract
+            facts = []
+            def fact(label, value):
+                facts.append({"label": label, "value": text(value)})
+            fact("读取时间", read_at)
+            fact("Artifact kind", meta.kind)
+            fact("创建时间", meta.created_at.isoformat())
+            fact("内容身份", meta.content_hash)
+            fact("Evidence status", meta.evidence_status)
+            fact("完整行数", meta.row_count)
+            fact("公开语义引用", [{"role": item.role, "kind": item.semantic_kind.value, "path": item.semantic_path, "outputColumn": item.output_column} for item in contract.semantic_inputs])
+            quality = meta.quality_summary
+            fact("Quality", None if quality is None else {"coverage": quality.coverage, "nullRate": quality.null_rate, "sampleSize": quality.sample_size, "evaluatedCheckCount": quality.evaluated_check_count, "failedCheckCount": quality.failed_check_count, "warningCheckCount": quality.warning_check_count})
+            fact("Issues", [{"kind": item.kind, "severity": item.severity} for item in contract.issues])
+            if "findingId" in ref:
+                try:
+                    finding = artifact.finding(ref["findingId"])
+                    if finding.finding_id != ref["findingId"] or finding.artifact_ref != artifact.ref or finding.session_id != session.id:
+                        raise ProjectionFailure("source_identity_mismatch", source_path + "/ref/findingId", "Restored Finding identity differs from the declared source.")
+                    excerpt = finding.render(max_output_bytes=4096)
+                    fact("选择的 Finding", excerpt)
+                except ProjectionFailure:
+                    raise
+                except Exception:
+                    fact("选择的 Finding unavailable", "The requested Finding cannot be read through the persisted Artifact public API.")
+                    diagnostics.append({"code": "finding_unavailable", "path": source_path + "/ref/findingId", "message": "Artifact is available; its requested Finding is unavailable."})
+            if meta.kind == "metric_frame" or any(item.semantic_kind.value == "metric" for item in contract.semantic_inputs):
+                definition_sources.append(declared["id"])
+                fact("指标定义说明", "信息：Artifact 公开契约未提供生成时的指标定义快照，来源概要无法展示当时的指标含义与口径。不影响已保存数据、图表及已有代码的展示，正常阅读无需处理；核验历史口径需补充生成时的定义快照，当前语义层定义不能替代历史定义。")
+            fact("revalidation", "not_requested")
+            sources.append({**declared, "status": "available", "label": text(str(meta.kind) + " " + artifact.ref, 512), "facts": facts, "code": sql_code_snapshot(session, artifact)})
+
+        if definition_sources:
+            diagnostics.append({"code": "definition_unavailable", "path": "/sources", "message": "信息：" + str(len(definition_sources)) + " 个指标来源的 Artifact 公开契约未提供生成时的指标定义快照，来源概要无法展示当时的指标含义与口径。不影响已保存数据、图表及已有代码的展示，正常阅读无需处理；核验历史口径需补充生成时的定义快照，当前语义层定义不能替代历史定义。"})
+
+        for selection in request["datasets"]:
+            dataset_path = "/datasets/" + str(selection["index"])
+            artifact = artifacts.get(selection["sourceId"])
+            if artifact is None:
+                raise ProjectionFailure("artifact_data_unavailable", dataset_path + "/sourceId", "A direct Artifact dataset requires an available persisted Artifact source.")
+            try:
+                contract = contracts[selection["sourceId"]]
+                frame = artifact.to_pandas()
+                public_columns = list(contract.artifact_schema.columns)
+                if list(frame.columns) != [column.name for column in public_columns] or len(frame) != artifact.meta.row_count or artifact.row_count != len(frame):
+                    raise ProjectionFailure("artifact_data_identity_mismatch", dataset_path, "Artifact rows or columns disagree with its public contract.")
+                names = selection.get("columns", list(frame.columns))
+                by_name = {column.name: column for column in public_columns}
+                if any(name not in by_name for name in names):
+                    raise ProjectionFailure("invalid_reference", dataset_path + "/columns", "A requested column is absent from the public Artifact schema.")
+                # Use public terminal values; declared upstream dtypes cannot recover
+                # Decimal precision already lost by to_pandas(). No derived metrics.
+                data = encode_dataset(frame.loc[:, names], row_limit=selection["rowLimit"])
+                for column in data["columns"]:
+                    column["nullable"] = by_name[column["id"]].nullable
+                datasets.append({"id": selection["id"], "data": data})
+            except ProjectionFailure:
+                raise
+            except Exception as error:
+                # Preserve helper contract locations without leaking upstream error text.
+                code = getattr(error, "code", None)
+                location = getattr(error, "path", None)
+                if code in ("numeric_precision", "budget", "invalid_value") and isinstance(location, str):
+                    raise ProjectionFailure(code, dataset_path + "/data" + location, "Public Artifact values cannot be encoded within the presentation data contract.") from None
+                raise ProjectionFailure("artifact_data_unavailable", dataset_path + "/data", "The direct Artifact does not expose the required typed presentation data.") from None
+        return {"ok": True, "sources": sources, "datasets": datasets, "diagnostics": diagnostics}
+    finally:
+        for session in sessions.values():
+            session.close()
+
+
+try:
+    request = json.loads(sys.argv[1])
+    with md.credential_scope(resolver=DenyCredentials()):
+        result = read(request)
+except ProjectionFailure as error:
+    result = {"ok": False, "error": {"code": error.code, "path": error.path, "message": error.message}}
+except Exception:
+    result = {"ok": False, "error": {"code": "projection_read_failed", "path": "/sources", "message": "The bound public presentation read failed."}}
+print(json.dumps(result, ensure_ascii=False, allow_nan=False, separators=(",", ":")))
+`.trim();

package/lib/presentation/projection/sql-code.js

@@ -0,0 +1,79 @@
+/** Only persisted public producer records are read; this program never compiles or executes SQL. */
+export const MARIVO_PRESENTATION_SQL_CODE_PROGRAM = String.raw `
+def sql_code_snapshot(session, artifact):
+    snippets, notices = [], []
+    def notice(message):
+        if message not in notices:
+            notices.append(message)
+    def valid_string(value, limit):
+        return isinstance(value, str) and bool(value) and "\0" not in value and len(value.encode("utf-16-le")) // 2 <= limit
+
+    try:
+        succeeded_run = mv.SucceededRun
+        get_run = session.get_run
+    except Exception:
+        return {"snippets": [], "notices": ["当前 Marivo 未提供读取持久化 SQL 所需的公开 Run 能力。"]}
+
+    pending = [(artifact.ref, artifact)]
+    scheduled, runs, seen_queries = {artifact.ref}, {}, set()
+    query_count = 0
+    for expected_ref, known_artifact in pending:
+        try:
+            current = known_artifact if known_artifact is not None else session.artifact(expected_ref)
+            meta, contract = current.meta, current.contract()
+            if current.ref != expected_ref or contract.ref != expected_ref or meta.session_id != session.id or Path(meta.project_root).resolve() != Path.cwd().resolve():
+                notice("部分上游 Artifact 的身份或 Workspace 不一致，已拒绝读取其 SQL。")
+                continue
+            producer = meta.produced_by_job
+            if producer is None:
+                notice("部分 Artifact 未保存生产 Run 标识，无法读取其生成 SQL。")
+                continue
+            if not valid_string(producer, 512):
+                notice("部分 Artifact 的生产 Run 标识无效，已拒绝读取其 SQL。")
+                continue
+            run = runs.get(producer)
+            if run is None:
+                run = get_run(producer)
+                runs[producer] = run
+            if not isinstance(run, succeeded_run) or run.run_id != producer or run.output_mode != "produced" or run.output_artifact_ref != expected_ref:
+                notice("部分生产 Run 的身份、完成状态或产出不匹配，已拒绝读取其 SQL。")
+                continue
+            for query in run.queries:
+                if query_count >= 32:
+                    notice("SQL 快照最多读取 32 条查询记录，其余记录未纳入。")
+                    break
+                query_count += 1
+                query_id = query.query_id
+                if not valid_string(query_id, 512):
+                    notice("部分 SQL 记录的查询标识无效，未纳入代码快照。")
+                    continue
+                query_key = (producer, query_id)
+                if query_key in seen_queries:
+                    continue
+                seen_queries.add(query_key)
+                sql = query.sql
+                if not valid_string(sql, 32768) or not sql.strip():
+                    notice("部分 SQL 为空、包含不支持的字符或超过 32768 字符，未截断也未纳入快照。")
+                    continue
+                snippets.append({"language": "sql", "text": sql, "provenance": "execution", "runId": producer, "queryId": query_id, "artifactRef": expected_ref})
+            for input_index, input_ref in enumerate(run.input_artifact_refs):
+                if input_index >= 65:
+                    notice("SQL 追溯最多读取 64 个上游 Artifact，其余来源未纳入。")
+                    break
+                if not valid_string(input_ref, 512):
+                    notice("部分上游 Artifact 标识无效，已停止该分支的 SQL 追溯。")
+                    continue
+                if input_ref in scheduled:
+                    continue
+                if len(scheduled) >= 65:
+                    notice("SQL 追溯最多读取 64 个上游 Artifact，其余来源未纳入。")
+                    break
+                scheduled.add(input_ref)
+                pending.append((input_ref, None))
+        except Exception:
+            # A missing record or capability affects code only. Never return exception text.
+            notice("部分持久化生产记录无法通过当前 Workspace 的公开 API 读取，SQL 快照可能不完整。")
+    if not snippets and not notices:
+        notice("该 Artifact 及已读取的上游生产记录未保存 SQL。")
+    return {"snippets": snippets, "notices": notices}
+`.trim();

package/lib/presentation/receipt.js

@@ -0,0 +1,34 @@
+/** Pure Host delivery envelope shared by the server and browser. */
+import { parsePresentationReceipt } from "./contracts/index.js";
+export const MARIVO_PRESENT_TOOL_NAME = 'marivo_present';
+export const MARIVO_PRESENTATION_DELIVERY_KIND = 'marivo.presentation.delivery';
+export const MARIVO_PRESENTATION_RPC_CHANNEL = '/marivo-presentation';
+export function parsePresentationDelivery(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('invalid-presentation-delivery');
+    const input = value;
+    if (Object.keys(input).sort().join(',') !== 'dshSessionId,kind,receipt,schemaVersion,turn' ||
+        input.kind !== MARIVO_PRESENTATION_DELIVERY_KIND ||
+        input.schemaVersion !== 2 ||
+        typeof input.dshSessionId !== 'string' ||
+        !input.dshSessionId.trim() ||
+        input.dshSessionId.length > 512 ||
+        !Number.isSafeInteger(input.turn) ||
+        input.turn < 0)
+        throw new Error('invalid-presentation-delivery');
+    parsePresentationReceipt(input.receipt);
+    return input;
+}
+export function presentationReceiptText(receipt) {
+    return [
+        receipt.title,
+        receipt.summary,
+        `Workspace: ${receipt.workspaceId}`,
+        `Report: ${receipt.reportId}`,
+        `Build: ${receipt.buildId}`,
+        ...Object.values(receipt.files).flatMap((file) => [
+            `${file.asset}: ${file.path}`,
+            `sha256: ${file.sha256}; bytes: ${file.bytes}`,
+        ]),
+    ].join('\n');
+}

package/lib/presentation/reports.js

@@ -0,0 +1,122 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, realpath, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { withFileLock } from '@deepseek-ai/dsh-atomic-write';
+import { buildPresentation } from "./build/index.js";
+import { commitPresentation } from "./commit.js";
+import { parsePresentationDocument, parsePresentationReceipt, } from "./contracts/index.js";
+import { presentationAssetPath, presentationReportPath, presentationSha256, readPresentationAsset, readReportFile, } from "./files.js";
+export async function readReceiptDocument(root, receipt, signal) {
+    for (const asset of Object.values(receipt.files)) {
+        if (asset.path !== presentationAssetPath(root, receipt.reportId, receipt.buildId, asset.asset))
+            throw new Error('asset-path-mismatch');
+    }
+    const bytes = await readPresentationAsset(root, receipt.reportId, receipt.buildId, 'presentation.json', signal);
+    if (bytes.length !== receipt.files.document.bytes ||
+        presentationSha256(bytes) !== receipt.files.document.sha256)
+        throw new Error('asset-digest-mismatch');
+    const document = parsePresentationDocument(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)));
+    if (document.workspaceId !== receipt.workspaceId ||
+        document.reportId !== receipt.reportId ||
+        document.buildId !== receipt.buildId ||
+        document.title !== receipt.title)
+        throw new Error('asset-owner-mismatch');
+    return document;
+}
+export async function resolvePresentation(root, workspaceId, reportId, signal) {
+    const bytes = await readReportFile(root, path.join(presentationReportPath(root, reportId), 'current.json'), 20 * 1024, signal);
+    const current = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    if (!current ||
+        Object.keys(current).sort().join(',') !== 'receipt,reportId,schemaVersion,workspaceId' ||
+        current.schemaVersion !== 2 ||
+        current.workspaceId !== workspaceId ||
+        current.reportId !== reportId)
+        throw new Error('invalid-report-current');
+    const receipt = parsePresentationReceipt(current.receipt);
+    if (receipt.workspaceId !== workspaceId || receipt.reportId !== reportId)
+        throw new Error('asset-owner-mismatch');
+    await readReceiptDocument(root, receipt, signal);
+    return receipt;
+}
+/** The mutable pointer is the publication boundary; completed builds are never overwritten. */
+export async function publishPresentation(root, document, expectedBuildId, assertOwner, signal) {
+    await assertOwner();
+    signal?.throwIfAborted();
+    const built = await buildPresentation(document);
+    await assertOwner();
+    const receipt = await commitPresentation(root, built, assertOwner, signal);
+    const directory = presentationReportPath(root, document.reportId);
+    const currentPath = path.join(directory, 'current.json');
+    const parents = [root];
+    for (const segment of path.relative(root, directory).split(path.sep))
+        parents.push(path.join(parents.at(-1), segment));
+    const identities = await Promise.all(parents.map((parent) => lstat(parent)));
+    const check = async () => {
+        signal?.throwIfAborted();
+        await assertOwner();
+        const actual = await Promise.all(parents.map((parent) => lstat(parent)));
+        if ((await realpath(directory)) !== directory ||
+            actual.some((entry, index) => !entry.isDirectory() ||
+                entry.isSymbolicLink() ||
+                entry.dev !== identities[index].dev ||
+                entry.ino !== identities[index].ino))
+            throw new Error('presentation-directory-changed');
+    };
+    await check();
+    await withFileLock(currentPath, async () => {
+        await check();
+        let current;
+        try {
+            current = await resolvePresentation(root, document.workspaceId, document.reportId, signal);
+        }
+        catch (error) {
+            if (expectedBuildId !== null || error.code !== 'ENOENT')
+                throw error;
+            // ENOENT is allowed only for an absent pointer, never a dangling current build.
+            try {
+                await lstat(currentPath);
+                throw new Error('invalid-report-current');
+            }
+            catch (missing) {
+                if (missing.code !== 'ENOENT')
+                    throw missing;
+            }
+        }
+        if ((current?.buildId ?? null) !== expectedBuildId)
+            throw new Error('report-save-conflict');
+        const temporary = path.join(directory, `.current-${randomUUID()}.tmp`);
+        let published = false;
+        try {
+            const file = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+            try {
+                await file.writeFile(JSON.stringify({
+                    schemaVersion: 2,
+                    workspaceId: document.workspaceId,
+                    reportId: document.reportId,
+                    receipt,
+                }), { signal });
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            await check();
+            await rename(temporary, currentPath);
+            published = true;
+            const parent = await open(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+            try {
+                await parent.sync();
+            }
+            finally {
+                await parent.close();
+            }
+            // Cancellation after the rename cannot undo a published save.
+        }
+        finally {
+            if (!published)
+                await rm(temporary, { force: true });
+        }
+    }, { waitMs: 5000 });
+    return receipt;
+}

package/lib/presentation/rpc.js

@@ -0,0 +1,148 @@
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { applyPresentationEdits } from "./contracts/editing.js";
+import { parsePresentationBuildId, parsePresentationDocument, parsePresentationReceipt, } from "./contracts/index.js";
+import { presentationAssetPath, presentationSha256, readPresentationAsset } from "./files.js";
+import { MARIVO_PRESENTATION_RPC_CHANNEL } from "./receipt.js";
+import { publishPresentation, readReceiptDocument, resolvePresentation } from "./reports.js";
+export class MarivoPresentationFileService {
+    #resolve;
+    #abort = new AbortController();
+    constructor(resolve) {
+        this.#resolve = resolve;
+    }
+    async #workspace(sessionId) {
+        try {
+            return await this.#resolve(sessionId);
+        }
+        catch {
+            throw new Error('workspace-unavailable');
+        }
+    }
+    close() {
+        this.#abort.abort();
+    }
+    async report(endpoint, payload, caller = new AbortController().signal) {
+        const signal = AbortSignal.any([caller, this.#abort.signal]);
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+            throw new Error('invalid-request');
+        const input = payload;
+        const expected = endpoint === 'reports/save'
+            ? 'edits,expectedBuildId,reportId,sessionId'
+            : 'reportId,sessionId';
+        if (Object.keys(input).sort().join(',') !== expected ||
+            typeof input.sessionId !== 'string' ||
+            !input.sessionId.trim() ||
+            input.sessionId.length > 512)
+            throw new Error('invalid-request');
+        const reportId = parsePresentationBuildId(input.reportId, '/reportId');
+        const workspace = await this.#workspace(input.sessionId);
+        if (!workspace)
+            throw new Error('workspace-unavailable');
+        const root = path.resolve(workspace.path);
+        const check = async () => {
+            signal.throwIfAborted();
+            const current = await this.#workspace(input.sessionId);
+            if (!current || current.id !== workspace.id || path.resolve(current.path) !== root)
+                throw new Error('workspace-changed');
+        };
+        await check();
+        const receipt = await resolvePresentation(root, workspace.id, reportId, signal);
+        await check();
+        if (endpoint === 'reports/resolve')
+            return receipt;
+        const expectedBuildId = parsePresentationBuildId(input.expectedBuildId);
+        if (receipt.buildId !== expectedBuildId)
+            throw new Error('report-save-conflict');
+        const base = await readReceiptDocument(root, receipt, signal);
+        let edited;
+        try {
+            edited = applyPresentationEdits(base, input.edits);
+        }
+        catch {
+            throw new Error('invalid-report-edits');
+        }
+        await check();
+        return publishPresentation(root, { ...edited, buildId: randomUUID(), generatedAt: new Date().toISOString() }, expectedBuildId, check, signal);
+    }
+    async read(payload, caller = new AbortController().signal) {
+        const signal = AbortSignal.any([caller, this.#abort.signal]);
+        signal.throwIfAborted();
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+            throw new Error('invalid-request');
+        const input = payload;
+        if (Object.keys(input).sort().join(',') !== 'asset,receipt,sessionId' ||
+            typeof input.sessionId !== 'string' ||
+            !input.sessionId.trim() ||
+            input.sessionId.length > 512 ||
+            (input.asset !== 'presentation.json' && input.asset !== 'index.html'))
+            throw new Error('invalid-request');
+        const receipt = structuredClone(parsePresentationReceipt(input.receipt));
+        const asset = input.asset;
+        const workspace = await this.#workspace(input.sessionId);
+        if (!workspace || workspace.id !== receipt.workspaceId)
+            throw new Error('workspace-unavailable');
+        const root = path.resolve(workspace.path);
+        for (const file of Object.values(receipt.files))
+            if (file.path !== presentationAssetPath(root, receipt.reportId, receipt.buildId, file.asset))
+                throw new Error('asset-path-mismatch');
+        const documentBytes = await readPresentationAsset(root, receipt.reportId, receipt.buildId, 'presentation.json', signal);
+        if (documentBytes.length !== receipt.files.document.bytes ||
+            presentationSha256(documentBytes) !== receipt.files.document.sha256)
+            throw new Error('asset-digest-mismatch');
+        const document = parsePresentationDocument(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(documentBytes)));
+        if (document.workspaceId !== workspace.id ||
+            document.reportId !== receipt.reportId ||
+            document.buildId !== receipt.buildId ||
+            document.title !== receipt.title)
+            throw new Error('asset-owner-mismatch');
+        const bytes = asset === 'presentation.json'
+            ? documentBytes
+            : await readPresentationAsset(root, receipt.reportId, receipt.buildId, asset, signal);
+        const file = asset === 'presentation.json' ? receipt.files.document : receipt.files.html;
+        if (bytes.length !== file.bytes || presentationSha256(bytes) !== file.sha256)
+            throw new Error('asset-digest-mismatch');
+        const current = await this.#workspace(input.sessionId);
+        if (!current || current.id !== workspace.id || path.resolve(current.path) !== root)
+            throw new Error('workspace-changed');
+        signal.throwIfAborted();
+        return {
+            workspaceId: workspace.id,
+            reportId: receipt.reportId,
+            buildId: receipt.buildId,
+            asset,
+            mimeType: asset === 'presentation.json' ? 'application/json' : 'text/html',
+            sha256: file.sha256,
+            bytes: bytes.length,
+            bodyBase64: bytes.toString('base64'),
+        };
+    }
+}
+export function registerMarivoPresentationRpc(connection, service) {
+    const unregister = connection.rpc.handle(MARIVO_PRESENTATION_RPC_CHANNEL, async (endpoint, payload, signal) => {
+        try {
+            if (endpoint === 'reports/resolve' || endpoint === 'reports/save')
+                return { ok: true, value: await service.report(endpoint, payload, signal) };
+            if (endpoint === 'files/read')
+                return { ok: true, value: await service.read(payload, signal) };
+            throw new Error('unknown-endpoint');
+        }
+        catch (error) {
+            const message = signal.aborted
+                ? 'cancelled'
+                : error?.code === 'ENOENT'
+                    ? 'asset-missing'
+                    : error instanceof Error &&
+                        /^(invalid-request|workspace-unavailable|workspace-changed|asset-path-mismatch|asset-not-file|asset-too-large|asset-changed|asset-digest-mismatch|asset-owner-mismatch|unknown-endpoint|invalid-report-current|invalid-report-edits|report-save-conflict|presentation-directory-changed)$/.test(error.message)
+                        ? error.message
+                        : error instanceof Error && /lock.*timed out|timed out.*lock/i.test(error.message)
+                            ? 'report-save-busy'
+                            : 'presentation-operation-failed';
+            return { ok: false, error: { code: 'internal', message, details: {} } };
+        }
+    }, { authority: 'trusted-host' });
+    return async () => {
+        service.close();
+        await unregister();
+    };
+}

package/lib/presentation/tool.js

@@ -0,0 +1,122 @@
+import { randomUUID } from 'node:crypto';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { parsePresentationBuildId } from "./contracts/index.js";
+import { MARIVO_PRESENT_TOOL_NAME, MARIVO_PRESENTATION_DELIVERY_KIND, parsePresentationDelivery, presentationReceiptText, } from "./receipt.js";
+import { publishPresentation, resolvePresentation } from "./reports.js";
+/** One call projects a draft, builds both assets, commits them, then emits the receipt. */
+export function createMarivoPresentTool(source, session, lifecycleSignal) {
+    return defineTool({
+        name: MARIVO_PRESENT_TOOL_NAME,
+        description: 'Present a complete Workspace-relative analysis draft as one saved document and self-contained offline HTML. Omit report_id and expected_build_id to create a Report; provide both to replace an existing Report with a new immutable Build based on the version you have read. A report-save-conflict requires reading the current report and reconciling the draft; never retry by only changing expected_build_id. Returns the exact published receipt, file locations, and a reader card. Only saved Artifact and computed snapshots are read; sources are declarations, not verification of calculations.',
+        parameters: {
+            draft_path: {
+                type: 'string',
+                required: true,
+                description: 'Workspace-relative path of the complete presentation draft JSON. Updates replace the whole report content; omitted content is not preserved.',
+            },
+            report_id: {
+                type: 'string',
+                description: 'Existing Report ID in the current Workspace to update. Must be provided together with expected_build_id; omit both to create a new Report.',
+            },
+            expected_build_id: {
+                type: 'string',
+                description: 'Build ID of the report version you have read and based this complete draft on. Must be provided together with report_id. A stale version fails with report-save-conflict; read and reconcile the current report before retrying.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: { deliveryJson: { type: 'string', required: true } },
+            },
+            render: (_args, value) => [
+                {
+                    type: 'text',
+                    text: presentationReceiptText(parsePresentationDelivery(JSON.parse(value.deliveryJson)).receipt),
+                },
+            ],
+            presentationMeta: (_args, value) => JSON.parse(value.deliveryJson),
+        },
+        timeoutMs: 120_000,
+        async execute(args, exec) {
+            const signal = lifecycleSignal ? AbortSignal.any([exec.signal, lifecycleSignal]) : exec.signal;
+            if (typeof args.draft_path !== 'string' ||
+                args.draft_path.length === 0 ||
+                args.draft_path.length > 4096)
+                throw new Error('invalid-draft-path');
+            const hasReportId = args.report_id !== undefined;
+            const hasExpectedBuildId = args.expected_build_id !== undefined;
+            if (hasReportId !== hasExpectedBuildId)
+                throw new Error('invalid-report-update-target');
+            const reportId = hasReportId
+                ? parsePresentationBuildId(args.report_id, '/report_id')
+                : randomUUID();
+            const expectedBuildId = hasExpectedBuildId
+                ? parsePresentationBuildId(args.expected_build_id, '/expected_build_id')
+                : null;
+            const owner = exec.agent;
+            if (!owner || owner.session !== session)
+                throw new Error('presentation-session-mismatch');
+            const rootCallId = String(exec.rootCallId ?? exec.callId);
+            const call = [...session.events]
+                .reverse()
+                .find((event) => event.type === 'tool/call' && String(event.data.callId) === rootCallId);
+            if (call?.type !== 'tool/call' || !Number.isSafeInteger(call.data.turn) || call.data.turn < 0)
+                throw new Error('presentation-turn-unavailable');
+            signal.throwIfAborted();
+            const binding = await source();
+            const identity = {
+                workspaceId: binding.workspaceId,
+                projectRoot: binding.projection.binding.projectRoot,
+                fingerprint: binding.projection.binding.fingerprint,
+            };
+            const check = async () => {
+                signal.throwIfAborted();
+                if (owner.session !== session)
+                    throw new Error('presentation-session-mismatch');
+                const current = await source();
+                if (current.projection.status !== 'ready' ||
+                    current.workspaceId !== identity.workspaceId ||
+                    current.projection.binding.projectRoot !== identity.projectRoot ||
+                    current.projection.binding.fingerprint !== identity.fingerprint ||
+                    current.projection.binding !== binding.projection.binding)
+                    throw new Error('presentation-workspace-changed');
+                signal.throwIfAborted();
+            };
+            await check();
+            if (expectedBuildId !== null) {
+                const current = await resolvePresentation(identity.projectRoot, identity.workspaceId, reportId, signal);
+                await check();
+                if (current.buildId !== expectedBuildId)
+                    throw new Error('report-save-conflict');
+            }
+            const draft = await binding.projection.readDraft(args.draft_path, signal);
+            await check();
+            const document = await binding.projection.project(draft, {
+                workspaceId: binding.workspaceId,
+                reportId,
+                buildId: randomUUID(),
+                signal,
+            });
+            await check();
+            const receipt = await publishPresentation(identity.projectRoot, document, expectedBuildId, check, signal);
+            return {
+                deliveryJson: JSON.stringify(parsePresentationDelivery({
+                    kind: MARIVO_PRESENTATION_DELIVERY_KIND,
+                    schemaVersion: 2,
+                    dshSessionId: String(session.id),
+                    turn: call.data.turn,
+                    receipt,
+                })),
+            };
+        },
+    });
+}
+export function registerMarivoPresentTool(ctx, source, session) {
+    const controller = new AbortController();
+    const unregister = ctx.tools.register(createMarivoPresentTool(source, session, controller.signal));
+    return () => {
+        controller.abort();
+        unregister();
+    };
+}

package/lib/python-execution-contracts.js

@@ -0,0 +1 @@
+export {};