@chengxianglibra/dsh-data-analysis 0.1.1 → 0.2.0

package/lib/presentation/projection/index.js

@@ -0,0 +1,196 @@
+import { MarivoEnvironmentError } from "../../environment/errors.js";
+import { readPythonExecution } from "../../python-execution.js";
+import { PRESENTATION_BUDGETS, PresentationContractError, parsePresentationDocument, parsePresentationDraft, parseTypedDataset, } from "../contracts/index.js";
+import { readWorkspaceJson } from "./files.js";
+import { MARIVO_PRESENTATION_READ_PROGRAM } from "./program.js";
+export { readWorkspaceJson } from "./files.js";
+function invalidOutput() {
+    throw new MarivoEnvironmentError('subprocess-output-invalid', 'Marivo presentation reader returned an invalid projection.');
+}
+function record(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        invalidOutput();
+    return value;
+}
+function exactKeys(value, keys) {
+    if (Object.keys(value).sort().join(',') !== keys.sort().join(','))
+        invalidOutput();
+}
+/** Internal S2 bridge: restores public data without observe, revalidation or credential admission. */
+export class MarivoPresentationProjection {
+    #runner;
+    constructor(runner) {
+        this.#runner = runner;
+    }
+    get status() {
+        return this.#runner.status;
+    }
+    get binding() {
+        return this.#runner.binding;
+    }
+    async readDraft(relativePath, signal) {
+        this.#assertReady(signal);
+        return parsePresentationDraft(await readWorkspaceJson(this.binding.projectRoot, relativePath, PRESENTATION_BUDGETS.draftBytes, '/draft_path', signal));
+    }
+    #assertReady(signal) {
+        signal?.throwIfAborted();
+        if (this.#runner.status !== 'ready')
+            throw new MarivoEnvironmentError('binding-failed', 'Presentation projection requires a ready bound Runtime.');
+        if (!this.binding.presentationKit)
+            throw new MarivoEnvironmentError('binding-identity-mismatch', 'Presentation projection requires the checked presentation helper identity.');
+    }
+    async project(value, options) {
+        this.#assertReady(options.signal);
+        // Snapshot caller-owned input before awaiting IO.
+        const draft = structuredClone(parsePresentationDraft(value));
+        const datasets = [];
+        const artifactSelections = draft.datasets.flatMap((dataset, index) => dataset.kind === 'artifact'
+            ? [
+                {
+                    id: dataset.id,
+                    kind: dataset.kind,
+                    sourceId: dataset.sourceId,
+                    rowLimit: dataset.rowLimit,
+                    ...(dataset.columns ? { columns: dataset.columns } : {}),
+                    index,
+                },
+            ]
+            : []);
+        let sources = [];
+        let diagnostics = [];
+        const artifactData = new Map();
+        if (draft.sources.length > 0) {
+            const result = await this.#runner.runChecked({
+                program: MARIVO_PRESENTATION_READ_PROGRAM,
+                args: [JSON.stringify({ sources: draft.sources, datasets: artifactSelections })],
+                limits: {
+                    timeoutMs: 30_000,
+                    stdoutMaxBytes: PRESENTATION_BUDGETS.documentBytes,
+                    stderrMaxBytes: 65_536,
+                },
+                signal: options.signal,
+            });
+            this.#assertReady(options.signal);
+            if (result.exitCode !== 0)
+                throw new MarivoEnvironmentError('subprocess-failed', 'The bound Marivo presentation read failed.', { exitCode: result.exitCode });
+            let payload;
+            try {
+                payload = record(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(result.stdout)));
+            }
+            catch {
+                invalidOutput();
+            }
+            if (payload.ok === false) {
+                exactKeys(payload, ['ok', 'error']);
+                const error = record(payload.error);
+                exactKeys(error, ['code', 'path', 'message']);
+                if (typeof error.code !== 'string' ||
+                    !/^[a-z_]{1,128}$/.test(error.code) ||
+                    typeof error.path !== 'string' ||
+                    error.path.length > 1024 ||
+                    !/^(?:\/(?:[^~]|~[01])*)*$/.test(error.path) ||
+                    typeof error.message !== 'string' ||
+                    error.message.length > 1024)
+                    invalidOutput();
+                throw new PresentationContractError(error.code, error.path, error.message);
+            }
+            exactKeys(payload, ['ok', 'sources', 'datasets', 'diagnostics']);
+            if (payload.ok !== true ||
+                !Array.isArray(payload.sources) ||
+                !Array.isArray(payload.datasets) ||
+                !Array.isArray(payload.diagnostics))
+                invalidOutput();
+            if (payload.sources.length !== draft.sources.length ||
+                payload.datasets.length !== artifactSelections.length)
+                invalidOutput();
+            for (const [index, source] of payload.sources.entries()) {
+                const actual = record(source);
+                const ref = record(actual.ref);
+                const expected = draft.sources[index];
+                if (actual.id !== expected.id ||
+                    ref.sessionId !== expected.ref.sessionId ||
+                    ref.artifactRef !== expected.ref.artifactRef ||
+                    ref.findingId !== expected.ref.findingId)
+                    invalidOutput();
+            }
+            for (const [index, entry] of payload.datasets.entries()) {
+                const dataset = record(entry);
+                exactKeys(dataset, ['id', 'data']);
+                if (dataset.id !== artifactSelections[index].id)
+                    invalidOutput();
+                artifactData.set(artifactSelections[index].id, dataset.data);
+            }
+            sources = payload.sources;
+            diagnostics = payload.diagnostics;
+        }
+        for (const [index, dataset] of draft.datasets.entries()) {
+            this.#assertReady(options.signal);
+            const location = `/datasets/${index}`;
+            let data;
+            if (dataset.kind === 'computed') {
+                data = await readWorkspaceJson(this.binding.projectRoot, dataset.path, PRESENTATION_BUDGETS.datasetBytes, `${location}/path`, options.signal);
+            }
+            else
+                data = artifactData.get(dataset.id);
+            data = parseTypedDataset(data, `${location}/data`);
+            if (dataset.kind === 'artifact') {
+                const typed = data;
+                if (typed.limit > dataset.rowLimit ||
+                    (dataset.columns !== undefined &&
+                        (typed.columns.length !== dataset.columns.length ||
+                            typed.columns.some((column, index) => column.id !== dataset.columns[index]))))
+                    invalidOutput();
+            }
+            const code = [];
+            for (const [codeIndex, ref] of (dataset.codeRefs ?? []).entries()) {
+                this.#assertReady(options.signal);
+                try {
+                    code.push(await readPythonExecution(this.binding.projectRoot, ref, options.signal));
+                }
+                catch {
+                    options.signal?.throwIfAborted();
+                    throw new PresentationContractError('code_unavailable', `${location}/codeRefs/${codeIndex}`, 'The captured Python execution cannot be read with its exact Workspace identity and digest.', 'Check the codeRef returned by the successful marivo_python call; do not rerun analysis to repair presentation.');
+                }
+            }
+            this.#assertReady(options.signal);
+            datasets.push({
+                id: dataset.id,
+                origin: dataset.kind,
+                data: data,
+                sourceIds: dataset.kind === 'artifact' ? [dataset.sourceId] : dataset.sourceIds,
+                ...(dataset.codeRefs !== undefined ? { code } : {}),
+            });
+        }
+        for (const [index, dataset] of datasets.entries()) {
+            if (dataset.data.truncated)
+                diagnostics.push({
+                    code: 'truncated',
+                    path: `/datasets/${index}/data/rows`,
+                    message: `Showing ${dataset.data.rows.length} of ${dataset.data.rowCount} rows; truncated data must not imply full totals or rankings.`,
+                });
+        }
+        for (const [index, source] of sources.entries()) {
+            if (source.status === 'unavailable')
+                diagnostics.push({
+                    code: 'source_unavailable',
+                    path: `/sources/${index}`,
+                    message: 'The declared Artifact source cannot be restored in the bound Workspace.',
+                });
+        }
+        this.#assertReady(options.signal);
+        return parsePresentationDocument({
+            schemaVersion: 3,
+            locale: draft.locale,
+            reportId: options.reportId,
+            workspaceId: options.workspaceId,
+            buildId: options.buildId,
+            title: draft.title,
+            generatedAt: options.generatedAt ?? new Date().toISOString(),
+            datasets,
+            sources,
+            blocks: draft.blocks,
+            ...(draft.interaction ? { interaction: draft.interaction } : {}),
+            diagnostics,
+        });
+    }
+}

package/lib/presentation/projection/program.js

@@ -0,0 +1,137 @@
+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 = [], [], []
+    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": "marivo.presentation.source-unavailable"})
+                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", "marivo.presentation.finding-unavailable")
+                    diagnostics.append({"code": "finding_unavailable", "path": source_path + "/ref/findingId", "message": "Artifact is available; its requested Finding is unavailable."})
+            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)})
+
+        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.presentation.sql-capability-unavailable"]}
+
+    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("marivo.presentation.sql-artifact-mismatch")
+                continue
+            producer = meta.produced_by_job
+            if producer is None:
+                notice("marivo.presentation.sql-producer-missing")
+                continue
+            if not valid_string(producer, 512):
+                notice("marivo.presentation.sql-producer-invalid")
+                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("marivo.presentation.sql-run-mismatch")
+                continue
+            for query in run.queries:
+                if query_count >= 32:
+                    notice("marivo.presentation.sql-query-limit")
+                    break
+                query_count += 1
+                query_id = query.query_id
+                if not valid_string(query_id, 512):
+                    notice("marivo.presentation.sql-query-invalid")
+                    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("marivo.presentation.sql-sql-invalid")
+                    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("marivo.presentation.sql-upstream-limit")
+                    break
+                if not valid_string(input_ref, 512):
+                    notice("marivo.presentation.sql-upstream-invalid")
+                    continue
+                if input_ref in scheduled:
+                    continue
+                if len(scheduled) >= 65:
+                    notice("marivo.presentation.sql-upstream-limit")
+                    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("marivo.presentation.sql-read-unavailable")
+    if not snippets and not notices:
+        notice("marivo.presentation.sql-not-saved")
+    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,219 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, opendir, 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 { parseReportHistory, REPORT_HISTORY_BYTES, REPORT_HISTORY_LIMIT, } from "./contracts/catalog.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;
+}
+/** Current and its publication history become visible through one atomic rename. */
+export async function readReportHistory(root, workspaceId, reportId, signal) {
+    const bytes = await readReportFile(root, path.join(presentationReportPath(root, reportId), 'current.json'), REPORT_HISTORY_BYTES, signal);
+    const current = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    if (!current || 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');
+    if (current.schemaVersion === 2 &&
+        Object.keys(current).sort().join(',') === 'receipt,reportId,schemaVersion,workspaceId') {
+        return {
+            workspaceId,
+            reportId,
+            currentBuildId: receipt.buildId,
+            legacyHistoryUnavailable: true,
+            versions: [{ receipt, publishedAt: null, source: null }],
+        };
+    }
+    if (current.schemaVersion !== 3 ||
+        Object.keys(current).sort().join(',') !==
+            'legacyHistoryUnavailable,receipt,reportId,schemaVersion,versions,workspaceId')
+        throw new Error('invalid-report-current');
+    const history = parseReportHistory({
+        workspaceId,
+        reportId,
+        currentBuildId: receipt.buildId,
+        legacyHistoryUnavailable: current.legacyHistoryUnavailable,
+        versions: current.versions,
+    });
+    if (JSON.stringify(history.versions[0].receipt) !== JSON.stringify(receipt))
+        throw new Error('invalid-report-history');
+    return history;
+}
+export async function resolvePresentation(root, workspaceId, reportId, signal) {
+    const history = await readReportHistory(root, workspaceId, reportId, signal);
+    const receipt = history.versions[0].receipt;
+    await readReceiptDocument(root, receipt, signal);
+    return receipt;
+}
+/** Enumerate only publication pointers, never completed-but-unpublished build directories. */
+export async function listReports(root, workspaceId, signal) {
+    const directory = path.dirname(presentationReportPath(root, 'catalog'));
+    const parents = [root, path.dirname(directory), directory];
+    const identities = [];
+    try {
+        for (const name of parents) {
+            const stat = await lstat(name);
+            if (!stat.isDirectory() || stat.isSymbolicLink() || (await realpath(name)) !== name)
+                throw new Error('asset-path-mismatch');
+            identities.push(stat);
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { workspaceId, reports: [], unavailable: 0 };
+        throw error;
+    }
+    const reports = [];
+    let unavailable = 0, count = 0;
+    for await (const entry of await opendir(directory)) {
+        signal?.throwIfAborted();
+        if (++count > 4096)
+            throw new Error('report-catalog-too-large');
+        if (entry.name.startsWith('.'))
+            continue;
+        try {
+            if (!entry.isDirectory() || entry.isSymbolicLink())
+                throw new Error('asset-not-file');
+            const history = await readReportHistory(root, workspaceId, entry.name, signal);
+            reports.push(history.versions[0]);
+        }
+        catch (error) {
+            signal?.throwIfAborted();
+            if (error.code !== 'ENOENT')
+                unavailable++;
+        }
+    }
+    for (const [index, name] of parents.entries()) {
+        const stat = await lstat(name);
+        if (stat.dev !== identities[index].dev ||
+            stat.ino !== identities[index].ino ||
+            stat.isSymbolicLink() ||
+            (await realpath(name)) !== name)
+            throw new Error('asset-path-mismatch');
+    }
+    reports.sort((a, b) => (b.publishedAt ?? '').localeCompare(a.publishedAt ?? '') ||
+        a.receipt.reportId.localeCompare(b.receipt.reportId));
+    return { workspaceId, reports, unavailable };
+}
+/** The mutable pointer is the publication boundary; completed builds are never overwritten. */
+export async function publishPresentation(root, document, expectedBuildId, assertOwner, signal, source = null) {
+    await assertOwner();
+    signal?.throwIfAborted();
+    const built = await buildPresentation(document, { html: false });
+    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 history;
+        let current;
+        try {
+            history = await readReportHistory(root, document.workspaceId, document.reportId, signal);
+            current = history.versions[0].receipt;
+            await readReceiptDocument(root, current, 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 versions = [
+            { receipt, publishedAt: new Date().toISOString(), source },
+            ...(history?.versions ?? []),
+        ];
+        if (versions.length > REPORT_HISTORY_LIMIT)
+            throw new Error('report-history-full');
+        parseReportHistory({
+            workspaceId: document.workspaceId,
+            reportId: document.reportId,
+            currentBuildId: receipt.buildId,
+            legacyHistoryUnavailable: history?.legacyHistoryUnavailable ?? false,
+            versions,
+        });
+        const pointer = JSON.stringify({
+            schemaVersion: 3,
+            workspaceId: document.workspaceId,
+            reportId: document.reportId,
+            receipt,
+            versions,
+            legacyHistoryUnavailable: history?.legacyHistoryUnavailable ?? false,
+        });
+        if (Buffer.byteLength(pointer) > REPORT_HISTORY_BYTES)
+            throw new Error('report-history-full');
+        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(pointer, { 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;
+}