Using OpenChainGraph with Export Profiles

Three layers: provenance-out, knowledge-in, rendered-for-review

v0.3 introduced a two-layer framing — OKF (context-in) and OCG (provenance-out). v0.4 extends it to three. Export Profiles are the third layer: a rendered-for-review surface that takes an already-verified artifact and produces the file format a human, pipeline, or regulator actually opens. Understanding what this layer does — and does not do — is the foundation of a correct integration.

The three layers interlock cleanly and derive from the same source artifact: an agent consults OKF to plan a chain, executes it to receive a signed OCG artifact, and — only when a human, pipeline, or regulator needs to consume that artifact outside a JSON parser — calls export_artifact to render it. The planning surface, the proof surface, and the review surface never overlap.

This separation is also why export profiles are additive, not a dependency. Nothing in OCG's verification path reads or depends on the rendered files. The export layer is a convenience for the last mile of consumption; removing it would not affect the cryptographic integrity of any artifact.

The chaingraph_export umbrella

In OpenChainGraph v0.4, every export format is a documented sub-profile under one umbrella term: chaingraph_export:<format>. This mirrors the OKF companion bundle's precedent (§10 of the spec) — a generated view, never hand-edited, never independently verifiable, fully swappable, and additive. No existing tool, kernel, or verifier changes to remain v0.4-valid.

chaingraph_export:xlsx   // analyst / board spreadsheet — this guide's lead profile
chaingraph_export:csv    // pipeline-tabular sibling of xlsx — near-free once xlsx exists
chaingraph_export:pdf    // signed board / audit one-pager
chaingraph_export:xbrl   // regulator-submission profile (taxonomy per regime)

Every sub-profile, regardless of format, must satisfy the same five conformance rules. These are the rules that make "generated, swappable, additive" actually true rather than aspirational:

Generation: one canonical generator, server-side

Export generation runs in the Cloudflare Worker — the same runtime as the Compute-Binding kernels (§12 of the spec) — as one canonical generator rather than N drifting client implementations. The rationale mirrors Compute Binding: agent-native, single round-trip, reproducible. The zero-egress privacy boundary applies unchanged here too: exporters are pure functions over an artifact the caller already holds. No payload is logged, stored, or transmitted beyond the JSON-RPC response.

Exporters live at repo/chaingraph/exporters/<format>/ — parallel to kernels/ — each a pure function with the same shape:

// buildExport(artifact) → Uint8Array
// Pure: no DOM, no window, no network, no Date.now().
// Receives the full verified v0.4 artifact object; returns the rendered bytes.
// Vendored into the Worker by generate.mjs on the same push (same
// two-repo discipline as kernels — see Compute Binding §12.3).
export async function buildExport(artifact) { … }

// Static metadata for the Worker's export registry.
export const meta = { format: "xlsx", media_type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" };

The export_artifact MCP tool

Export Profiles surface through a single new read-only MCP tool — not a format parameter bolted onto every existing tool (which would inflate every schema in the suite), and not an out-of-band HTTP endpoint (which would split the agent-callable story in two). This follows MCP best practice: a focused, domain-aware tool that an agent can reason about on its own, with one tool owning the render concern end-to-end.

// Input
{
  "artifact":       // full v0.4 artifact object (REQUIRED — stateless Worker, no cache)
  "format":         "xlsx" | "pdf" | "csv" | "xbrl",
  "xbrl_taxonomy":  "<regime id>"   // required only when format = xbrl
}

// Output
{
  "format":      "xlsx",
  "filename":    "<tool_id>-<short_hash>.xlsx",
  "media_type":  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "bytes_base64": "…",           // standard base64 (NOT url-safe) — avoids client decode bugs
  "metadata":    { "tool_id", "execution_hash", "chaingraph_version", "compute_mode" }
}

The agent flow stays end-to-end and entirely MCP-native: call a compute tool → receive a JSON artifact with execution_hash → call export_artifact with that artifact → receive the rendered file. Both calls are readOnlyHint:true, so an agent (or a policy layer governing one) can treat the whole sequence as side-effect-free.

chaingraph_export:xlsx — workbook convention

xlsx is the lead export profile and the one with the most direct mapping to existing tool output: most OCG tools already produce tabular output_payload shapes (percentile tables, batch rows, distributions), so the exporter's job is largely extraction and layout rather than transformation. Every xlsx export follows a fixed three-sheet convention:

The workbook is generated with a Workers-compatible OOXML writer — pure JS/WASM, no Node fs dependency. Given the simple, deterministic structure (three fixed sheet roles, no formulas, no macros, no embedded objects beyond the QR image), a minimal hand-rolled OOXML writer is an acceptable implementation choice; nothing about the format requires a full-featured spreadsheet library.

Determinism (conformance rule 5, §2) applies in full here: sorted rows, fixed number formats, and a static per-mandate_type sheet layout mean the same artifact run through the same exporter version always produces a byte-identical .xlsx file. Two analysts holding the same artifact can confirm — without opening the JSON — that they're looking at the same workbook.

Discovering what a tool can export: export_capability

Mirroring compute_capability from Compute Binding, every live node in chaingraph.json may declare which export profiles it supports — so MCP clients and agents can discover available formats before calling export_artifact, rather than finding out by trial and error.

{
  "tool_id":            "compute_rwa_scenarios",
  "compute_capability": "server",
  "export_capability":  ["xlsx", "csv", "xbrl:eba-corep-own-funds"]
}

This gives the Graph Index / DCAT surface a discovery signal symmetric with compute_capability: an agent or static-site generator walking chaingraph.json can build a "what can I do with this artifact" menu without a single failed export_artifact call.

The other three profiles: csv, pdf, xbrl

xlsx is the lead profile for this guide, but the umbrella has three siblings, each tuned to a different consumer. All four share the same export_artifact call shape and the same five conformance rules from §2 — only the rendering differs.

The xbrl taxonomy landscape at v0.4:

Integration checklist

Six steps to wire up Export Profiles end-to-end, from artifact to rendered file. Each step is independently verifiable.