Module workbook 

Governed-Excel workbook served-tool module (Phase 92).

Gated behind the opt-in workbook feature so the no-workbook toolkit build never links the pmcp-workbook-runtime BundleSource/BundleLoader surface. The workbook-embedded feature additionally enables the runtime’s embedded (include_dir) EmbeddedSource for binary-baked bundles. Governed-Excel workbook served-tool module (Phase 92, bundlesource-served-tool-toolkit-module).

This is the toolkit-side home for the served calculate / explain / get_manifest / diff_version / render_workbook tools that operate on a verified pmcp_workbook_runtime::WorkbookBundle (loaded fail-closed via the runtime’s BundleSource + BundleLoader).

Domain failure vs infrastructure failure (Codex LOW)

The served tools draw a sharp line between two failure classes:

• A domain failure (invalid input, an out-of-range / non-finite output, a strict-constant override) is NOT a protocol error. It returns isError:true INSIDE structuredContent via [error::to_iserror_result] so the MCP App widget can read a stable, machine-actionable repair code — never an Err(pmcp::Error).
• An infrastructure failure (a poisoned/malformed in-memory bundle state, a resource-handler internal fault, a genuine bug) MAY still surface as a protocol Err. The lift does NOT blanket-swallow infrastructure faults as domain errors.

The served provenance stamp ([ProvStamp], Codex HIGH #3)

Every tool result (success AND error envelope) carries a [ProvStamp] of { bundle_id, version, combined_hash }. The combined_hash field carries the BUNDLE.lock COMBINED hash-of-hashes (pmcp_workbook_runtime::BundleLock::combined). It is named combined_hash — NEVER workbook_hash — so it can never be confused with pmcp_workbook_runtime::BundleLock::workbook_hash, which is the SOURCE workbook content hash, a DIFFERENT value.

Modules

error

The structured isError:true envelope (WBSV-06) — machine-actionable repair payloads that ride in structuredContent, NEVER a JSON-RPC protocol error, and ALWAYS carry the provenance stamp (on the failure path too).

handler

The curated workbook tool handlers (WBSV-01/02/03/04): calculate, explain, get_manifest, diff_version.

input

The strict calculate/explain input DTO + fail-closed tier enforcement (WBSV-06, WR-02/WR-05/V4).

render_resource

The stateless regen-on-read workbook:// resource handler (WBSV-05, V3/V12).

render_uri

The workbook:// render-pointer URI codec (WBSV-05, V12).

schema

Tool schema builders (WBSV-07) — the mandatory non-empty outputSchema + the per-tool input schema, projected ENTIRELY from the embedded Manifest + CellMap.

Structs

CellMap

Re-export of the verified runtime bundle the served tools operate on (loaded fail-closed via pmcp_workbook_runtime::load_bundle). The manifest-driven I/O cell map (Codex HIGH #5): the shared inputs pool + the per-Table Tools the served binary fans out into one MCP tool each (WBV2-03 §4.1).

DecodedRender

The decoded render payload: the canonical input DTO plus the provenance stamp that was bound into the URI at render_workbook time.

DiffVersionHandler

The diff_version handler (WBSV-04): serve the RECORDED prev→current pmcp_workbook_runtime::VersionChangelog the offline promote step folded into the bundle (hash-verified at boot — NOT a runtime computation), stamped.

EmbeddedSource

The binary-baked BundleSource (WBSV-09), re-exported only when the toolkit’s workbook-embedded feature layers the runtime’s embedded (include_dir) support on top of the LocalDirSource-only workbook build.

ExplainHandler

The explain handler (WBSV-02): a stateless re-run that renders the derivation trace as ordered business-language steps, plus a GENERIC manifest-declared annotations object (S-2 — any domain-specific keystone is generalized into manifest-declared annotations; the engine reads only manifest.annotations names, nothing domain-specific).

GetManifestHandler

The get_manifest handler (WBSV-03): a CURATED agent-facing projection — inputs (tier+default+unit), outputs (unit/meaning), governed-data summary, versions/hashes, changelog — NOT the raw internal manifest.

LocalDirSource

Re-export of the full boot surface (D-11) so Shape A/B consumers register a served workbook WITHOUT ever naming pmcp-workbook-runtime: the BundleSource trait + its on-disk impl, the fail-closed loader entry point, and both error types. The EmbeddedSource impl is re-exported separately under the workbook-embedded feature (it needs the runtime’s embedded include_dir support). A BundleSource that reads a bundle from a directory tree on disk.

Manifest

Re-export of the verified runtime bundle the served tools operate on (loaded fail-closed via pmcp_workbook_runtime::load_bundle). The logical manifest — the source of truth for cell roles + metadata that REPLACES colour as canonical (DIA-03). Synthesis builds a CANDIDATE (ratified = false); BA ratification (Plan 05) makes it conformant.

ProvStamp

The provenance stamp on EVERY served tool result (success AND error envelope) — the bundle_id@version identity plus the combined_hash integrity anchor (Codex HIGH #3).

RenderWorkbookHandler

The render_workbook handler (WBSV-05): validate the inputs, then return a provenance-bound workbook:// URI POINTER — NOT the .xlsx bytes. The bytes are recomputed per resources/read by super::render_resource from the decoded URI (stateless regen-on-read, Lambda-safe, V3).

RenderWorkbookResource

The stateless regen-on-read resource handler for workbook:// render pointers (WBSV-05). Holds the shared verified bundle; every read regenerates the .xlsx from the (untrusted) URI — provenance-verified, re-validated, re-run, rendered, base64-encoded.

ValidatedInput

A validated, tier-checked input ready to seed the pmcp_workbook_runtime executor. seeds is cell_key -> value (the inputs mapped through the embedded cell_map, plus any accepted variable-tier overrides).

WorkbookBundle

Re-export of the verified runtime bundle the served tools operate on (loaded fail-closed via pmcp_workbook_runtime::load_bundle). The fully-parsed, integrity-verified bundle the served tools operate on.

WorkbookToolError

One structured tool-execution error (WBSV-06): a machine-actionable repair payload. The agent reads allowed/range/required to repair the call — “allowed-values live in the error”.

WorkbookToolHandler

One served MCP tool per output Table (WBV2-04): validate → seed via cell_map → re-run the embedded IR → project ONLY this tool’s outputs (finite) → stamp.

Enums

BundleLoadError

Re-export of the full boot surface (D-11) so Shape A/B consumers register a served workbook WITHOUT ever naming pmcp-workbook-runtime: the BundleSource trait + its on-disk impl, the fail-closed loader entry point, and both error types. The EmbeddedSource impl is re-exported separately under the workbook-embedded feature (it needs the runtime’s embedded include_dir support). Errors load surfaces — every one is fail-closed (the bundle is rejected, the server never boots on a tampered/malformed bundle).

BundleSourceError

Re-export of the full boot surface (D-11) so Shape A/B consumers register a served workbook WITHOUT ever naming pmcp-workbook-runtime: the BundleSource trait + its on-disk impl, the fail-closed loader entry point, and both error types. The EmbeddedSource impl is re-exported separately under the workbook-embedded feature (it needs the runtime’s embedded include_dir support). Errors a BundleSource may surface.

Constants

MAX_ENCODED_URI_LEN

The hard upper bound on an encoded workbook:// URI length, in bytes.

WORKBOOK_TOOL_UI

The UI resource URI every workbook tool advertises (MCP Apps widget hook).

WORKBOOK_XLSX_MIME

The MIME type of the rendered .xlsx workbook (the OOXML spreadsheet type). Advertised by render_workbook and carried on the resources/read content so the client knows the base64 payload is a downloadable spreadsheet.

Traits

BundleSource

Re-export of the full boot surface (D-11) so Shape A/B consumers register a served workbook WITHOUT ever naming pmcp-workbook-runtime: the BundleSource trait + its on-disk impl, the fail-closed loader entry point, and both error types. The EmbeddedSource impl is re-exported separately under the workbook-embedded feature (it needs the runtime’s embedded include_dir support). Raw-byte access to a single bundle’s members.

WorkbookBuilderExt

Composable builder extension wiring a verified workbook bundle into a pmcp::ServerBuilder in ONE call.

Functions

decode

Decode a workbook:// render pointer URI back into its DecodedRender payload — TOTAL and panic-free over arbitrary/adversarial input.

encode

Encode a validated input DTO + provenance stamp into a workbook:// render pointer URI.

load_bundle

Re-export of the full boot surface (D-11) so Shape A/B consumers register a served workbook WITHOUT ever naming pmcp-workbook-runtime: the BundleSource trait + its on-disk impl, the fail-closed loader entry point, and both error types. The EmbeddedSource impl is re-exported separately under the workbook-embedded feature (it needs the runtime’s embedded include_dir support). Load + fail-closed integrity-verify a bundle from any BundleSource.

sanitize_tool_name

Sanitize a raw output-Table name into an MCP tool name matching ^[a-zA-Z0-9_-]{1,64}$ (T-100-10), wrapping the SINGLE shared runtime sanitizer (pmcp_workbook_runtime::sanitize_tool_name) so the served registration and the offline compiler’s collision lint cannot drift on the locked five-rule semantics (lowercase, illegal-run → single _, trim edges, truncate 64, reject empty/all-illegal). A reject becomes the fail-closed invalid_tool_name domain error.

to_iserror_result

Render a WorkbookToolError into the isError:true payload carrying the provenance stamp (on the failure path too). Returned as a bare Value — the widget-meta tool routes it into structuredContent where the isError:true marker + repair fields survive dispatch.

validate_input

Validate + tier-check the raw tool args against the manifest + cell_map, fail-closed.