@arnilo/prism-tools 0.0.0-stage → 0.13.0

package/work/src/connectors/types.ts

@@ -0,0 +1,399 @@
+import { JsonObject, OwnershipScope, ToolDefinition, ToolExecutionContext } from "@arnilo/prism";
+import { ArtifactBodyRef, ArtifactBodyStore } from "@arnilo/prism/artifacts";
+import type { WorkSandboxFilesystem } from "../tools/filesystem.js";
+import { AgentIdentity } from "./identity.js";
+export type WorkProvider = "microsoft365" | "google-workspace";
+
+export type Microsoft365Capability = "mail" | "calendar" | "files" | "tasks" | "todo" | "planner" | "teams";
+
+export type Microsoft365Op =
+  | "version"
+  | "mail.list"
+  | "mail.get"
+  | "mail.send"
+  | "calendar.list"
+  | "calendar.add"
+  | "file.list"
+  | "file.get"
+  | "file.add"
+  | "file.copy"
+  | "file.share"
+  | "todo.list"
+  | "todo.add"
+  | "todo.complete"
+  | "planner.list"
+  | "planner.add"
+  | "planner.complete";
+
+export type GoogleWorkspaceCapability = "mail" | "calendar" | "files" | "tasks" | "docs" | "sheets" | "slides";
+
+export type GoogleWorkspaceOp =
+  | "version"
+  | "mail.list"
+  | "mail.get"
+  | "mail.send"
+  | "calendar.list"
+  | "calendar.add"
+  | "file.list"
+  | "file.get"
+  | "file.add"
+  | "file.share"
+  | "task.list"
+  | "task.add"
+  | "task.complete"
+  | "docs.create"
+  | "docs.update"
+  | "sheets.create"
+  | "sheets.update"
+  | "slides.create"
+  | "slides.update";
+
+export interface WorkLimits {
+  readonly maxPaginationPages?: number;
+  readonly maxItemsPerPage?: number;
+  readonly maxAggregateItems?: number;
+  readonly maxRequestBytes?: number;
+  readonly maxResponseBytes?: number;
+  readonly maxAttachmentBytes?: number;
+  readonly maxFileBytes?: number;
+  readonly maxStdoutBytes?: number;
+  readonly maxStderrBytes?: number;
+  readonly timeoutMs?: number;
+  readonly maxConcurrency?: number;
+  readonly maxRetries?: number;
+  readonly maxIdempotencyKeyBytes?: number;
+  readonly maxJsonDepth?: number;
+  readonly maxJsonProperties?: number;
+}
+export type ResolvedWorkLimits = Required<WorkLimits>;
+
+export interface WorkCitation {
+  readonly citationId: string;
+  readonly provider: WorkProvider;
+  readonly resourceId?: string;
+  readonly url?: string;
+}
+
+export interface WorkMailMessage extends WorkCitation {
+  readonly subject?: string;
+  readonly preview?: string;
+  readonly from?: string;
+  readonly to?: readonly string[];
+  readonly receivedAt?: string;
+  readonly isDraft?: boolean;
+  readonly changeKey?: string;
+  readonly untrusted: true;
+}
+
+export interface WorkCalendarEvent extends WorkCitation {
+  readonly subject?: string;
+  readonly start?: string;
+  readonly end?: string;
+  readonly changeKey?: string;
+  readonly untrusted: true;
+}
+
+export interface WorkFileItem extends WorkCitation {
+  readonly name?: string;
+  readonly size?: number;
+  readonly eTag?: string;
+  readonly mimeType?: string;
+  readonly untrusted: true;
+}
+
+export interface WorkTaskItem extends WorkCitation {
+  readonly title?: string;
+  readonly status?: string;
+  readonly changeKey?: string;
+  readonly untrusted: true;
+}
+
+export interface WorkPage<T> {
+  readonly items: readonly T[];
+  readonly nextCursor?: string;
+  readonly truncated?: boolean;
+  readonly untrusted: true;
+}
+
+export interface WorkDraftApproval {
+  readonly draftId: string;
+  readonly revision: number;
+  readonly payloadDigest: string;
+  readonly policyRevision?: string;
+  readonly identityKey?: string;
+  readonly approver?: string;
+  readonly approvedAt?: string;
+  readonly expiresAt?: string;
+}
+
+export interface WorkDraft {
+  readonly draftId: string;
+  readonly provider: WorkProvider;
+  readonly op: string;
+  readonly identityKey: string;
+  readonly payload: JsonObject;
+  readonly revision: number;
+  readonly payloadDigest: string;
+  readonly recipients?: readonly string[];
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly status: "pending" | "pending_approval" | "approved" | "executed" | "rejected" | "unknown";
+  readonly approval?: WorkDraftApproval;
+  readonly concurrencyToken?: string;
+  readonly executedAt?: string;
+  readonly bodyRef?: ArtifactBodyRef;
+  readonly policyRevision?: string;
+  readonly mode?: "ephemeral" | "durable";
+}
+
+export interface WorkDraftCreateInput {
+  readonly draftId?: string;
+  readonly provider: WorkProvider;
+  readonly op: string;
+  readonly identity: AgentIdentity;
+  readonly payload: JsonObject;
+  readonly policyRevision?: string;
+  readonly signal?: AbortSignal;
+}
+
+export interface WorkDraftRefInput {
+  readonly draftId: string;
+  readonly identity: AgentIdentity;
+  readonly provider?: WorkProvider;
+  readonly signal?: AbortSignal;
+}
+
+export interface WorkDraftUpdateInput {
+  readonly draftId: string;
+  readonly identity: AgentIdentity;
+  readonly payload: JsonObject;
+  readonly expectedRevision?: number;
+  readonly expectedConcurrencyToken?: string;
+  readonly policyRevision?: string;
+  readonly signal?: AbortSignal;
+}
+
+export interface WorkDraftApproveInput {
+  readonly draftId: string;
+  readonly identity: AgentIdentity;
+  readonly approval: WorkDraftApproval;
+  readonly expectedConcurrencyToken?: string;
+  readonly signal?: AbortSignal;
+}
+
+export interface WorkDraftMarkInput {
+  readonly draftId: string;
+  readonly identity: AgentIdentity;
+  readonly status: WorkDraft["status"];
+  readonly concurrencyToken?: string;
+  readonly expectedConcurrencyToken?: string;
+  readonly signal?: AbortSignal;
+}
+
+export interface WorkDraftStore {
+  readonly mode: "ephemeral" | "durable";
+  createDraft(input: WorkDraftCreateInput): Promise<WorkDraft> | WorkDraft;
+  getDraft(input: WorkDraftRefInput): Promise<WorkDraft | undefined> | WorkDraft | undefined;
+  updateDraft(input: WorkDraftUpdateInput): Promise<WorkDraft> | WorkDraft;
+  approveDraft(input: WorkDraftApproveInput): Promise<WorkDraft> | WorkDraft;
+  markDraft(input: WorkDraftMarkInput): Promise<WorkDraft> | WorkDraft;
+}
+
+export interface SyncWorkDraftStore extends WorkDraftStore {
+  createDraft(input: WorkDraftCreateInput): WorkDraft;
+  getDraft(input: WorkDraftRefInput): WorkDraft | undefined;
+  updateDraft(input: WorkDraftUpdateInput): WorkDraft;
+  approveDraft(input: WorkDraftApproveInput): WorkDraft;
+  markDraft(input: WorkDraftMarkInput): WorkDraft;
+}
+
+/** Bounded summary retained after an approved external mutation. */
+export interface WorkMutationResult {
+  readonly draftId: string;
+  readonly resourceId?: string;
+}
+
+export interface WorkMutationFailure {
+  readonly code: string;
+  readonly reference?: string;
+}
+
+export type WorkMutationStatus = "in_progress" | "completed" | "failed_retryable" | "failed_terminal" | "unknown";
+
+export interface WorkMutationKey {
+  /** Active host-verified identity; its exact owner/principal scopes this mutation. */
+  readonly identity: AgentIdentity;
+  readonly key: string;
+  readonly op: string;
+  readonly signal?: AbortSignal;
+}
+
+export interface WorkMutationBeginInput extends WorkMutationKey {
+  readonly claimTtlMs?: number;
+  readonly maxAttempts?: number;
+}
+
+export interface WorkMutationTransitionInput extends WorkMutationKey {
+  readonly claimToken: string;
+  readonly expectedVersion: number;
+}
+
+export interface WorkMutationRecord extends OwnershipScope {
+  readonly principalId: string;
+  readonly key: string;
+  readonly op: string;
+  readonly status: WorkMutationStatus;
+  readonly attempt: number;
+  readonly version: number;
+  readonly claimToken?: string;
+  readonly result?: WorkMutationResult;
+  readonly failure?: WorkMutationFailure;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly expiresAt?: string;
+}
+
+export interface IdempotencyStore {
+  /**
+   * Reconciliation read. Normal execution starts with {@link begin}.
+   *
+   * Adapters reject with the portable codes `ERR_PRISM_WORK_IDEMPOTENCY` (rejected
+   * claim/transition) and `ERR_PRISM_WORK_IDEMPOTENCY_CONFLICT` (lost race or stale
+   * claim token). The error class is adapter-specific — a memory store throws
+   * `WorkToolError`, the PostgreSQL adapter throws `EnterprisePostgresError` — so
+   * hosts match on {@link WorkToolError.code}, never on `instanceof`.
+   */
+  get(input: WorkMutationKey): Promise<WorkMutationRecord | undefined>;
+  begin(input: WorkMutationBeginInput): Promise<{ readonly outcome: "acquired" | "existing"; readonly record: WorkMutationRecord }>;
+  complete(input: WorkMutationTransitionInput & { readonly result: WorkMutationResult }): Promise<WorkMutationRecord>;
+  fail(
+    input: WorkMutationTransitionInput & { readonly status: "failed_retryable" | "failed_terminal"; readonly failure: WorkMutationFailure },
+  ): Promise<WorkMutationRecord>;
+  markUnknown(input: WorkMutationTransitionInput & { readonly failure?: WorkMutationFailure }): Promise<WorkMutationRecord>;
+  resolveUnknown(
+    input: WorkMutationKey & {
+      readonly expectedVersion: number;
+      readonly status: "failed_retryable" | "failed_terminal";
+      readonly failure?: WorkMutationFailure;
+    },
+  ): Promise<WorkMutationRecord>;
+}
+
+export interface WorkApprovalCheckInput {
+  readonly draftId: string;
+  readonly op: string;
+  readonly identity: AgentIdentity;
+  readonly revision?: number;
+  readonly payloadDigest?: string;
+  readonly recipients?: readonly string[];
+  readonly policyRevision?: string;
+}
+
+export interface WorkApprovalGate {
+  /** Return true or an approval decision when host already authorized this draft/mutation. */
+  isApproved(
+    input: WorkApprovalCheckInput | { draftId: string; op: string; identity: AgentIdentity },
+  ): Promise<boolean | WorkDraftApproval> | boolean | WorkDraftApproval;
+}
+
+export interface ExternalRecipientPolicy {
+  /** Return true when address/domain may receive external share/mail. Default deny. */
+  allow(address: string): boolean;
+}
+
+export interface WorkCliExecResult {
+  readonly exitCode: number | null;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+export interface WorkCliRunner {
+  exec(argv: readonly string[], options?: { signal?: AbortSignal; env?: Readonly<Record<string, string>> }): Promise<WorkCliExecResult>;
+}
+
+/**
+ * Late-bound, per-identity connector token source. Returns env vars to inject (e.g.
+ * `{ M365_ACCESSTOKEN: "…" }`) or undefined when the credential is missing/expired/revoked,
+ * which fails the call closed. Tokens never appear in argv or model context.
+ */
+export interface WorkTokenProvider {
+  tokenEnv(
+    identity: AgentIdentity,
+    signal?: AbortSignal,
+  ): Promise<Readonly<Record<string, string>> | undefined> | Readonly<Record<string, string>> | undefined;
+}
+
+export interface Microsoft365Adapter {
+  readonly provider: "microsoft365";
+  readonly identity: AgentIdentity;
+  readonly allowedOps: ReadonlySet<Microsoft365Op>;
+  readonly draftStore?: WorkDraftStore;
+  ensureReady(signal?: AbortSignal): Promise<string>;
+  runOp(op: Microsoft365Op, args: JsonObject, signal?: AbortSignal): Promise<unknown>;
+  createDraft(
+    op: Microsoft365Op,
+    payload: JsonObject,
+    options?: { draftId?: string; policyRevision?: string },
+  ): Promise<WorkDraft> | WorkDraft;
+  getDraft(draftId: string): Promise<WorkDraft | undefined> | WorkDraft | undefined;
+  updateDraft?(
+    draftId: string,
+    payload: JsonObject,
+    options?: { expectedRevision?: number; concurrencyToken?: string },
+  ): Promise<WorkDraft> | WorkDraft;
+  approveDraft?(approval: WorkDraftApproval): Promise<WorkDraft> | WorkDraft;
+  markDraft(draftId: string, status: WorkDraft["status"], concurrencyToken?: string): Promise<WorkDraft> | WorkDraft;
+}
+
+export interface GoogleWorkspaceAdapter {
+  readonly provider: "google-workspace";
+  readonly identity: AgentIdentity;
+  readonly allowedOps: ReadonlySet<GoogleWorkspaceOp>;
+  readonly draftStore?: WorkDraftStore;
+  ensureReady(signal?: AbortSignal): Promise<string>;
+  runOp(op: GoogleWorkspaceOp, args: JsonObject, signal?: AbortSignal): Promise<unknown>;
+  createDraft(
+    op: GoogleWorkspaceOp,
+    payload: JsonObject,
+    options?: { draftId?: string; policyRevision?: string },
+  ): Promise<WorkDraft> | WorkDraft;
+  getDraft(draftId: string): Promise<WorkDraft | undefined> | WorkDraft | undefined;
+  updateDraft?(
+    draftId: string,
+    payload: JsonObject,
+    options?: { expectedRevision?: number; concurrencyToken?: string },
+  ): Promise<WorkDraft> | WorkDraft;
+  approveDraft?(approval: WorkDraftApproval): Promise<WorkDraft> | WorkDraft;
+  markDraft(draftId: string, status: WorkDraft["status"], concurrencyToken?: string): Promise<WorkDraft> | WorkDraft;
+}
+
+export interface WorkFileArtifactStore {
+  readonly bodies: ArtifactBodyStore;
+  /** Host owns artifact naming and ownership; work tools supply verified download metadata. */
+  createRef(input: {
+    readonly context: ToolExecutionContext;
+    readonly provider: WorkProvider;
+    readonly itemId?: string;
+    readonly mime: string;
+    readonly byteLength: number;
+    readonly contentHash: string;
+  }): ArtifactBodyRef;
+}
+
+export interface WorkToolsOptions {
+  readonly microsoft365?: Microsoft365Adapter;
+  /** File-byte limit for tool-side artifact and filesystem transfers; match adapter limits when overridden. */
+  readonly limits?: WorkLimits;
+  readonly googleWorkspace?: GoogleWorkspaceAdapter;
+  readonly approval?: WorkApprovalGate;
+  readonly idempotencyStore?: IdempotencyStore;
+  readonly externalRecipients?: ExternalRecipientPolicy;
+  /** Optional contained filesystem used for downloaded files and sandbox-source uploads. */
+  readonly filesystem?: WorkSandboxFilesystem;
+  /** Optional host-owned artifact body store for downloaded files and sandbox-source uploads. */
+  readonly artifacts?: WorkFileArtifactStore;
+  /** Optional attachment/file scan before inbound use. Required for inbound attachment bytes. */
+  readonly scanAttachment?: (input: { bytes: number; name?: string }) => Promise<void> | void;
+}
+
+export type WorkToolSet = readonly ToolDefinition[];

package/work/src/diagrams/canonicalize.ts

@@ -0,0 +1,166 @@
+import { XMLParser } from "fast-xml-parser";
+import { type DrawioXmlCaps, type ResolvedDrawioXmlCaps, resolveDiagramsCaps, validateByteCap } from "./caps.js";
+import { DiagramsModelInvalidError, DiagramsXxeError } from "./errors.js";
+import type { DiagramsTelemetry } from "./telemetry.js";
+import { assertNotVisio, UNSAFE_XML_DECLARATION_PATTERN } from "./xml.js";
+
+export interface DrawioCanonicalizeOptions {
+  readonly caps?: DrawioXmlCaps;
+  readonly telemetry?: DiagramsTelemetry;
+}
+
+/**
+ * Produces byte-stable, canonicalized XML formatting for draw.io diagrams.
+ *
+ * Properties:
+ * - Attributes on all elements are sorted lexicographically by name ascending.
+ * - Double quotes are consistently used for attribute values.
+ * - XML entities are escaped in attribute values and text nodes.
+ * - Insignificant inter-tag and surrounding whitespace is stripped while element sequence is preserved.
+ * - Empty elements are normalized to self-closing form (`<element attr="val"/>`).
+ * - Deterministic output suitable for SHA-256 content hashing across systems.
+ */
+export function canonicalizeDrawioXml(xml: string | Uint8Array, options?: DrawioCanonicalizeOptions): string {
+  const startTime = Date.now();
+  const span = options?.telemetry?.startSpan("diagrams.canonicalize");
+
+  try {
+    assertNotVisio(xml);
+
+    const caps: ResolvedDrawioXmlCaps = resolveDiagramsCaps(options?.caps);
+    const xmlString = typeof xml === "string" ? xml : Buffer.from(xml).toString("utf8");
+    const byteLength = Buffer.byteLength(xmlString, "utf8");
+
+    validateByteCap(byteLength, caps);
+
+    if (UNSAFE_XML_DECLARATION_PATTERN.test(xmlString)) {
+      throw new DiagramsXxeError("XML contains forbidden DOCTYPE or ENTITY declaration (XXE security policy)");
+    }
+
+    const parser = new XMLParser({
+      preserveOrder: true,
+      ignoreAttributes: false,
+      attributeNamePrefix: "@_",
+      allowBooleanAttributes: false,
+      processEntities: false,
+      htmlEntities: false,
+      trimValues: false,
+      stopNodes: [],
+    });
+
+    const parsed: unknown = parser.parse(xmlString);
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+      throw new DiagramsModelInvalidError("Parsed XML does not produce an ordered element tree");
+    }
+
+    // Filter out top-level whitespace and XML processing instructions (?xml)
+    const rootNodes = (parsed as OrderedNode[]).filter(
+      (node) => !("#text" in node) && Object.keys(node).some((k) => !k.startsWith("?") && k !== ":@"),
+    );
+
+    if (rootNodes.length === 0) {
+      throw new DiagramsModelInvalidError("No valid root XML element found");
+    }
+
+    const canonicalOutput = serializeNodes(rootNodes);
+
+    span?.setAttribute("diagrams.inputBytes", byteLength);
+    span?.setAttribute("diagrams.outputBytes", Buffer.byteLength(canonicalOutput, "utf8"));
+    span?.setAttribute("diagrams.durationMs", Date.now() - startTime);
+
+    return canonicalOutput;
+  } catch (error) {
+    span?.recordError();
+    throw error;
+  } finally {
+    span?.end();
+  }
+}
+
+type OrderedNode = Record<string, unknown>;
+
+function serializeNodes(nodes: OrderedNode[]): string {
+  let result = "";
+  for (const node of nodes) {
+    result += serializeNode(node);
+  }
+  return result;
+}
+
+function serializeNode(node: OrderedNode): string {
+  if ("#text" in node) {
+    const rawText = String(node["#text"]);
+    return escapeXmlText(rawText);
+  }
+
+  // Find the element tag name (key that is not ":@" and does not start with "?")
+  let tagName: string | undefined;
+  for (const key of Object.keys(node)) {
+    if (key !== ":@" && !key.startsWith("?")) {
+      tagName = key;
+      break;
+    }
+  }
+
+  if (!tagName) {
+    return "";
+  }
+
+  const rawAttrs = (node[":@"] ?? {}) as Record<string, unknown>;
+  const sortedAttrs = Object.keys(rawAttrs)
+    .map((k) => (k.startsWith("@_") ? k.slice(2) : k))
+    .sort()
+    .map((attrName) => {
+      const originalKey = `@_${attrName}` in rawAttrs ? `@_${attrName}` : attrName;
+      const val = rawAttrs[originalKey];
+      return `${attrName}="${escapeXmlAttr(String(val ?? ""))}"`;
+    });
+
+  const attrString = sortedAttrs.length > 0 ? ` ${sortedAttrs.join(" ")}` : "";
+  const children = node[tagName];
+
+  if (!children || (Array.isArray(children) && children.length === 0)) {
+    return `<${tagName}${attrString}/>`;
+  }
+
+  if (Array.isArray(children)) {
+    // If element contains child elements, filter out insignificant whitespace-only text nodes
+    const hasElementChildren = children.some((c) => !("#text" in c));
+    const effectiveChildren = hasElementChildren
+      ? children.filter((c) => !("#text" in c) || String(c["#text"]).trim().length > 0)
+      : children;
+
+    if (effectiveChildren.length === 0) {
+      return `<${tagName}${attrString}/>`;
+    }
+
+    if (effectiveChildren.length === 1 && "#text" in effectiveChildren[0]!) {
+      const textVal = String(effectiveChildren[0]!["#text"]).trim();
+      if (textVal.length === 0) {
+        return `<${tagName}${attrString}/>`;
+      }
+      return `<${tagName}${attrString}>${escapeXmlText(textVal)}</${tagName}>`;
+    }
+
+    const childrenString = serializeNodes(effectiveChildren as OrderedNode[]);
+    return `<${tagName}${attrString}>${childrenString}</${tagName}>`;
+  }
+
+  if (typeof children === "string" || typeof children === "number" || typeof children === "boolean") {
+    const textStr = String(children).trim();
+    if (textStr.length === 0) {
+      return `<${tagName}${attrString}/>`;
+    }
+    return `<${tagName}${attrString}>${escapeXmlText(textStr)}</${tagName}>`;
+  }
+
+  return `<${tagName}${attrString}/>`;
+}
+
+function escapeXmlAttr(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+function escapeXmlText(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/work/src/diagrams/caps.ts

@@ -0,0 +1,52 @@
+import { DiagramsCapError } from "./errors.js";
+
+// --- Default and Hard Ceiling Constants ---
+
+export const DEFAULT_MAX_XML_BYTES = 32 * 1024 * 1024; // 32 MiB
+export const HARD_MAX_XML_BYTES = 512 * 1024 * 1024; // 512 MiB
+
+export const DEFAULT_MAX_ELEMENTS = 100_000;
+export const HARD_MAX_ELEMENTS = 500_000;
+
+export const DEFAULT_MAX_ATTRIBUTES = 500_000;
+export const HARD_MAX_ATTRIBUTES = 2_000_000;
+
+export interface DrawioXmlCaps {
+  readonly maxBytes?: number;
+  readonly maxElements?: number;
+  readonly maxAttributes?: number;
+}
+
+export interface ResolvedDrawioXmlCaps {
+  readonly maxBytes: number;
+  readonly maxElements: number;
+  readonly maxAttributes: number;
+}
+
+function resolveCap(name: string, value: number | undefined, defaultVal: number, hardCap: number): number {
+  if (value === undefined) return defaultVal;
+  if (!Number.isInteger(value) || value <= 0 || value > hardCap) {
+    throw new DiagramsCapError(`diagrams cap ${name} must be a positive integer in (0, ${hardCap}], got ${value}`);
+  }
+  return value;
+}
+
+/**
+ * Resolves user-supplied caps against safe defaults and hard ceilings.
+ */
+export function resolveDiagramsCaps(caps?: DrawioXmlCaps): ResolvedDrawioXmlCaps {
+  return {
+    maxBytes: resolveCap("maxBytes", caps?.maxBytes, DEFAULT_MAX_XML_BYTES, HARD_MAX_XML_BYTES),
+    maxElements: resolveCap("maxElements", caps?.maxElements, DEFAULT_MAX_ELEMENTS, HARD_MAX_ELEMENTS),
+    maxAttributes: resolveCap("maxAttributes", caps?.maxAttributes, DEFAULT_MAX_ATTRIBUTES, HARD_MAX_ATTRIBUTES),
+  };
+}
+
+/**
+ * Enforces input byte size ceiling. Throws {@link DiagramsCapError} if exceeded.
+ */
+export function validateByteCap(byteLength: number, caps: ResolvedDrawioXmlCaps): void {
+  if (byteLength > caps.maxBytes) {
+    throw new DiagramsCapError(`XML input size ${byteLength} bytes exceeds maxBytes cap (${caps.maxBytes})`);
+  }
+}