@arnilo/prism-tools 0.0.0-stage → 0.13.0

package/work/src/documents/caps.ts

@@ -0,0 +1,135 @@
+import { DocumentsCapError } from "./errors.js";
+import type { DeckModel, DocModel, DocumentModel, SheetModel } from "./types.js";
+
+// --- Default and Hard Ceiling Constants ---
+
+export const DEFAULT_MAX_DOCUMENT_BYTES = 32 * 1024 * 1024; // 32 MiB
+export const HARD_MAX_DOCUMENT_BYTES = 512 * 1024 * 1024; // 512 MiB
+
+export const DEFAULT_MAX_BLOCKS = 10_000;
+export const HARD_MAX_BLOCKS = 50_000;
+
+export const DEFAULT_MAX_CELLS = 500_000;
+export const HARD_MAX_CELLS = 2_000_000;
+
+export const DEFAULT_MAX_SLIDES = 500;
+export const HARD_MAX_SLIDES = 2_000;
+
+export const DEFAULT_MAX_SHEETS = 100;
+export const HARD_MAX_SHEETS = 1_000;
+
+export const DEFAULT_MAX_IMAGES = 100;
+export const HARD_MAX_IMAGES = 1_000;
+
+export interface DocumentCaps {
+  /** Maximum generated or parsed file size in bytes (default 32 MiB, hard 512 MiB). */
+  readonly maxBytes?: number;
+  /** Maximum total block elements in a doc model (default 10,000, hard 50,000). */
+  readonly maxBlocks?: number;
+  /** Maximum total table or worksheet cells (default 500,000, hard 2,000,000). */
+  readonly maxCells?: number;
+  /** Maximum presentation slides (default 500, hard 2,000). */
+  readonly maxSlides?: number;
+  /** Maximum workbook sheets (default 100, hard 1,000). */
+  readonly maxSheets?: number;
+  /** Maximum embedded images (default 100, hard 1,000). */
+  readonly maxImages?: number;
+}
+
+export interface ResolvedDocumentCaps {
+  readonly maxBytes: number;
+  readonly maxBlocks: number;
+  readonly maxCells: number;
+  readonly maxSlides: number;
+  readonly maxSheets: number;
+  readonly maxImages: 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 RangeError(`documents cap ${name} must be an integer in (0, ${hardCap}], got ${value}`);
+  }
+  return value;
+}
+
+/**
+ * Resolves user-supplied caps against safe defaults and hard ceilings.
+ */
+export function resolveDocumentCaps(caps?: DocumentCaps): ResolvedDocumentCaps {
+  return {
+    maxBytes: resolveCap("maxBytes", caps?.maxBytes, DEFAULT_MAX_DOCUMENT_BYTES, HARD_MAX_DOCUMENT_BYTES),
+    maxBlocks: resolveCap("maxBlocks", caps?.maxBlocks, DEFAULT_MAX_BLOCKS, HARD_MAX_BLOCKS),
+    maxCells: resolveCap("maxCells", caps?.maxCells, DEFAULT_MAX_CELLS, HARD_MAX_CELLS),
+    maxSlides: resolveCap("maxSlides", caps?.maxSlides, DEFAULT_MAX_SLIDES, HARD_MAX_SLIDES),
+    maxSheets: resolveCap("maxSheets", caps?.maxSheets, DEFAULT_MAX_SHEETS, HARD_MAX_SHEETS),
+    maxImages: resolveCap("maxImages", caps?.maxImages, DEFAULT_MAX_IMAGES, HARD_MAX_IMAGES),
+  };
+}
+
+/**
+ * Enforces element and structural caps on a DocumentModel before processing.
+ * Throws {@link DocumentsCapError} if any cap is exceeded.
+ */
+export function validateModelCaps(model: DocumentModel, caps: ResolvedDocumentCaps): void {
+  if (model.kind === "doc") {
+    const doc = model as DocModel;
+    if (doc.blocks.length > caps.maxBlocks) {
+      throw new DocumentsCapError(`document contains ${doc.blocks.length} blocks, exceeding maxBlocks cap (${caps.maxBlocks})`);
+    }
+    let cellCount = 0;
+    let imageCount = 0;
+    for (const block of doc.blocks) {
+      if (block.type === "table") {
+        for (const row of block.cells) {
+          cellCount += row.length;
+        }
+        if (cellCount > caps.maxCells) {
+          throw new DocumentsCapError(`document tables contain > ${caps.maxCells} cells, exceeding maxCells cap`);
+        }
+      } else if (block.type === "image") {
+        imageCount += 1;
+        if (imageCount > caps.maxImages) {
+          throw new DocumentsCapError(`document contains ${imageCount} images, exceeding maxImages cap (${caps.maxImages})`);
+        }
+      }
+    }
+  } else if (model.kind === "sheet") {
+    const sheetModel = model as SheetModel;
+    if (sheetModel.sheets.length > caps.maxSheets) {
+      throw new DocumentsCapError(`workbook contains ${sheetModel.sheets.length} sheets, exceeding maxSheets cap (${caps.maxSheets})`);
+    }
+    let cellCount = 0;
+    for (const sheet of sheetModel.sheets) {
+      for (const row of sheet.cells) {
+        cellCount += row.length;
+        if (cellCount > caps.maxCells) {
+          throw new DocumentsCapError(`sheet cells exceed maxCells cap (${caps.maxCells})`);
+        }
+      }
+    }
+  } else if (model.kind === "deck") {
+    const deck = model as DeckModel;
+    if (deck.slides.length > caps.maxSlides) {
+      throw new DocumentsCapError(`presentation contains ${deck.slides.length} slides, exceeding maxSlides cap (${caps.maxSlides})`);
+    }
+    let imageCount = 0;
+    for (const slide of deck.slides) {
+      if (slide.image) {
+        imageCount += 1;
+        if (imageCount > caps.maxImages) {
+          throw new DocumentsCapError(`presentation contains ${imageCount} images, exceeding maxImages cap (${caps.maxImages})`);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Enforces byte size ceiling. Throws {@link DocumentsCapError} if exceeded.
+ */
+export function validateByteCap(byteLength: number, caps: ResolvedDocumentCaps): void {
+  if (byteLength > caps.maxBytes) {
+    throw new DocumentsCapError(`document size ${byteLength} bytes exceeds maxBytes cap (${caps.maxBytes})`);
+  }
+}

package/work/src/documents/diff.ts

@@ -0,0 +1,269 @@
+import { DocumentsCapError, DocumentsValidationError } from "./errors.js";
+import { sha256Hex } from "./hash.js";
+import { validateDocumentModel } from "./model-schema.js";
+import type { CellValue, DeckModel, DocBlock, DocModel, DocumentKind, DocumentModel, ImageBlock, SheetModel, SlideData } from "./types.js";
+
+export const DEFAULT_MAX_DIFF_OPS = 4096;
+export const HARD_MAX_DIFF_OPS = 16_384;
+export const DEFAULT_MAX_DIFF_NODES = 8192;
+export const HARD_MAX_DIFF_NODES = 32_768;
+
+export type DocumentDiffOp = "add" | "remove" | "replace";
+
+export interface DocumentDiffChange {
+  readonly path: string;
+  readonly op: DocumentDiffOp;
+  readonly from?: unknown;
+  readonly to?: unknown;
+}
+
+export interface DocumentDiff {
+  readonly kind: DocumentKind;
+  readonly changes: readonly DocumentDiffChange[];
+  readonly truncated: boolean;
+  readonly operations: number;
+}
+
+export interface DiffDocumentOptions {
+  readonly maxOps?: number;
+  readonly maxNodes?: number;
+}
+
+function bound(name: string, value: number | undefined, fallback: number, hard: number): number {
+  if (value === undefined) return fallback;
+  if (!Number.isInteger(value) || value < 1 || value > hard) {
+    throw new DocumentsCapError(`${name} must be an integer in 1..${hard}`);
+  }
+  return value;
+}
+
+function clip(value: unknown): unknown {
+  if (typeof value === "string" && value.length > 256) return `${value.slice(0, 256)}…`;
+  return value;
+}
+
+function cellKey(value: CellValue): string {
+  if (value === null) return "null";
+  if (typeof value !== "object") return JSON.stringify(value);
+  if ("type" in value) return `${value.type}:${value.value}`;
+  if ("formula" in value) return `formula:${value.formula}:${String(value.cachedValue ?? "")}`;
+  return JSON.stringify(value);
+}
+
+function imageKey(image: ImageBlock): string {
+  const digest = image.data ? sha256Hex(Buffer.from(image.data)) : "";
+  return `${image.ref ?? ""}:${image.mimeType ?? ""}:${image.alt ?? ""}:${digest}`;
+}
+
+function blockKey(block: DocBlock): string {
+  switch (block.type) {
+    case "heading":
+      return `h${block.level}:${block.text}`;
+    case "paragraph":
+      return block.text ?? (block.runs ?? []).map((run) => run.text).join("");
+    case "list":
+      return JSON.stringify({ ordered: block.ordered ?? false, items: block.items });
+    case "page-break":
+      return "page-break";
+    case "image":
+      return imageKey(block);
+    case "chart":
+      return JSON.stringify({ chartType: block.chartType, title: block.title, data: block.data });
+    case "table":
+      return `table:${block.rows}x${block.columns}`;
+    default:
+      return JSON.stringify(block);
+  }
+}
+
+function slideKey(slide: SlideData): string {
+  return JSON.stringify({
+    layout: slide.layout,
+    title: slide.title,
+    subtitle: slide.subtitle,
+    bullets: slide.bullets,
+    notes: slide.notes,
+    image: slide.image ? imageKey(slide.image) : undefined,
+    chart: slide.chart,
+  });
+}
+
+interface Sink {
+  visit(): boolean;
+  emit(change: DocumentDiffChange): boolean;
+  truncated: boolean;
+  operations: number;
+  changes: DocumentDiffChange[];
+}
+
+function createSink(maxOps: number, maxNodes: number): Sink {
+  const changes: DocumentDiffChange[] = [];
+  let operations = 0;
+  let nodes = 0;
+  let truncated = false;
+  return {
+    get truncated() {
+      return truncated;
+    },
+    get operations() {
+      return operations;
+    },
+    get changes() {
+      return changes;
+    },
+    visit() {
+      if (truncated) return false;
+      if (nodes >= maxNodes) {
+        truncated = true;
+        return false;
+      }
+      nodes += 1;
+      return true;
+    },
+    emit(change) {
+      if (truncated) return false;
+      if (operations >= maxOps) {
+        truncated = true;
+        return false;
+      }
+      operations += 1;
+      changes.push({
+        path: change.path,
+        op: change.op,
+        ...(change.from === undefined ? {} : { from: clip(change.from) }),
+        ...(change.to === undefined ? {} : { to: clip(change.to) }),
+      });
+      return true;
+    },
+  };
+}
+
+function diffScalar(sink: Sink, path: string, from: unknown, to: unknown): boolean {
+  if (!sink.visit()) return false;
+  if (from === to) return true;
+  if (from === undefined) return sink.emit({ path, op: "add", to });
+  if (to === undefined) return sink.emit({ path, op: "remove", from });
+  return sink.emit({ path, op: "replace", from, to });
+}
+
+function diffCells(sink: Sink, path: string, from: readonly (readonly CellValue[])[], to: readonly (readonly CellValue[])[]): boolean {
+  const rows = Math.max(from.length, to.length);
+  for (let r = 0; r < rows; r += 1) {
+    const leftRow = from[r];
+    const rightRow = to[r];
+    if (!sink.visit()) return false;
+    if (leftRow === undefined) {
+      if (!sink.emit({ path: `${path}/${r}`, op: "add", to: rightRow?.map(cellKey) })) return false;
+      continue;
+    }
+    if (rightRow === undefined) {
+      if (!sink.emit({ path: `${path}/${r}`, op: "remove", from: leftRow.map(cellKey) })) return false;
+      continue;
+    }
+    const cols = Math.max(leftRow.length, rightRow.length);
+    for (let c = 0; c < cols; c += 1) {
+      const left = leftRow[c];
+      const right = rightRow[c];
+      if (left === undefined) {
+        if (!diffScalar(sink, `${path}/${r}/${c}`, undefined, right === undefined ? undefined : cellKey(right))) return false;
+        continue;
+      }
+      if (right === undefined) {
+        if (!diffScalar(sink, `${path}/${r}/${c}`, cellKey(left), undefined)) return false;
+        continue;
+      }
+      if (!diffScalar(sink, `${path}/${r}/${c}`, cellKey(left), cellKey(right))) return false;
+    }
+  }
+  return true;
+}
+
+function diffDoc(sink: Sink, from: DocModel, to: DocModel): boolean {
+  if (!diffScalar(sink, "title", from.title, to.title)) return false;
+  const n = Math.max(from.blocks.length, to.blocks.length);
+  for (let i = 0; i < n; i += 1) {
+    const left = from.blocks[i];
+    const right = to.blocks[i];
+    if (!sink.visit()) return false;
+    if (left === undefined) {
+      if (!sink.emit({ path: `blocks/${i}`, op: "add", to: right ? blockKey(right) : undefined })) return false;
+      continue;
+    }
+    if (right === undefined) {
+      if (!sink.emit({ path: `blocks/${i}`, op: "remove", from: blockKey(left) })) return false;
+      continue;
+    }
+    if (left.type !== right.type) {
+      if (!sink.emit({ path: `blocks/${i}`, op: "replace", from: blockKey(left), to: blockKey(right) })) return false;
+      continue;
+    }
+    if (left.type === "table" && right.type === "table") {
+      if (!diffCells(sink, `blocks/${i}/cells`, left.cells, right.cells)) return false;
+      continue;
+    }
+    if (!diffScalar(sink, `blocks/${i}`, blockKey(left), blockKey(right))) return false;
+  }
+  return true;
+}
+
+function diffSheet(sink: Sink, from: SheetModel, to: SheetModel): boolean {
+  if (!diffScalar(sink, "title", from.title, to.title)) return false;
+  const n = Math.max(from.sheets.length, to.sheets.length);
+  for (let i = 0; i < n; i += 1) {
+    const left = from.sheets[i];
+    const right = to.sheets[i];
+    if (!sink.visit()) return false;
+    if (left === undefined) {
+      if (!sink.emit({ path: `sheets/${i}`, op: "add", to: right?.name })) return false;
+      continue;
+    }
+    if (right === undefined) {
+      if (!sink.emit({ path: `sheets/${i}`, op: "remove", from: left.name })) return false;
+      continue;
+    }
+    if (!diffScalar(sink, `sheets/${i}/name`, left.name, right.name)) return false;
+    if (!diffCells(sink, `sheets/${i}/cells`, left.cells, right.cells)) return false;
+  }
+  return true;
+}
+
+function diffDeck(sink: Sink, from: DeckModel, to: DeckModel): boolean {
+  if (!diffScalar(sink, "title", from.title, to.title)) return false;
+  const n = Math.max(from.slides.length, to.slides.length);
+  for (let i = 0; i < n; i += 1) {
+    const left = from.slides[i];
+    const right = to.slides[i];
+    if (!sink.visit()) return false;
+    if (left === undefined) {
+      if (!sink.emit({ path: `slides/${i}`, op: "add", to: right ? slideKey(right) : undefined })) return false;
+      continue;
+    }
+    if (right === undefined) {
+      if (!sink.emit({ path: `slides/${i}`, op: "remove", from: slideKey(left) })) return false;
+      continue;
+    }
+    if (!diffScalar(sink, `slides/${i}`, slideKey(left), slideKey(right))) return false;
+  }
+  return true;
+}
+
+/** Structural Document Model diff. Caps report `truncated` instead of walking unbounded trees. Decimal cells compare as strings. */
+export function diffDocument(from: DocumentModel, to: DocumentModel, options?: DiffDocumentOptions): DocumentDiff {
+  validateDocumentModel(from);
+  validateDocumentModel(to);
+  if (from.kind !== to.kind) {
+    throw new DocumentsValidationError(`cannot diff "${from.kind}" against "${to.kind}"`);
+  }
+  const maxOps = bound("maxOps", options?.maxOps, DEFAULT_MAX_DIFF_OPS, HARD_MAX_DIFF_OPS);
+  const maxNodes = bound("maxNodes", options?.maxNodes, DEFAULT_MAX_DIFF_NODES, HARD_MAX_DIFF_NODES);
+  const sink = createSink(maxOps, maxNodes);
+  if (from.kind === "doc") diffDoc(sink, from, to as DocModel);
+  else if (from.kind === "sheet") diffSheet(sink, from, to as SheetModel);
+  else diffDeck(sink, from, to as DeckModel);
+  return {
+    kind: from.kind,
+    changes: Object.freeze(sink.changes),
+    truncated: sink.truncated,
+    operations: sink.operations,
+  };
+}

package/work/src/documents/errors.ts

@@ -0,0 +1,44 @@
+export class DocumentsError extends Error {
+  readonly code: string;
+
+  constructor(message: string, code = "ERR_PRISM_DOCUMENTS") {
+    super(message);
+    this.name = "DocumentsError";
+    this.code = code;
+  }
+}
+
+export class DocumentsCapError extends DocumentsError {
+  constructor(message: string) {
+    super(message, "ERR_PRISM_DOCUMENTS_CAP");
+    this.name = "DocumentsCapError";
+  }
+}
+
+export class DocumentsValidationError extends DocumentsError {
+  constructor(message: string) {
+    super(message, "ERR_PRISM_DOCUMENTS_INVALID_MODEL");
+    this.name = "DocumentsValidationError";
+  }
+}
+
+export class DocumentsFormatError extends DocumentsError {
+  constructor(message: string) {
+    super(message, "ERR_PRISM_DOCUMENTS_UNSUPPORTED_FORMAT");
+    this.name = "DocumentsFormatError";
+  }
+}
+
+export class DocumentsParseError extends DocumentsError {
+  constructor(message: string) {
+    super(message, "ERR_PRISM_DOCUMENTS_PARSE_FAILED");
+    this.name = "DocumentsParseError";
+  }
+}
+
+export class DocumentsPatchError extends DocumentsError {
+  constructor(message: string) {
+    super(message, "ERR_PRISM_DOCUMENTS_UNSAFE_PATH");
+    this.name = "DocumentsPatchError";
+  }
+}

package/work/src/documents/fidelity.ts

@@ -0,0 +1,98 @@
+import type { DocumentKind } from "./types.js";
+
+/** Cap on reported lost-structure issues (truncated after this). */
+export const HARD_FIDELITY_ISSUES = 256;
+const HARD_ZIP_ENTRIES = 8192;
+
+export type ImportFidelityLost = "dropped" | "approximated";
+
+export interface ImportFidelityIssue {
+  readonly code: string;
+  readonly part?: string;
+  readonly lost: ImportFidelityLost;
+}
+
+export interface ImportFidelityReport {
+  readonly kind: DocumentKind;
+  readonly issues: readonly ImportFidelityIssue[];
+  readonly truncated: boolean;
+}
+
+const EOCD = 0x06054b50;
+const CDFH = 0x02014b50;
+
+const RULES: ReadonlyArray<{ readonly match: RegExp; readonly code: string; readonly lost: ImportFidelityLost }> = [
+  { match: /(^|\/)vbaProject/i, code: "macros", lost: "dropped" },
+  { match: /EncryptionInfo|EncryptedPackage/i, code: "encrypted", lost: "dropped" },
+  { match: /^word\/comments/i, code: "comments", lost: "dropped" },
+  { match: /^xl\/(comments|threadedComments)/i, code: "comments", lost: "dropped" },
+  { match: /^word\/(header|footer)\d/i, code: "headers-footers", lost: "dropped" },
+  { match: /\/embeddings\//i, code: "embedded-ole", lost: "dropped" },
+  { match: /\/media\//i, code: "media", lost: "dropped" },
+  { match: /\/charts\//i, code: "charts", lost: "dropped" },
+  { match: /\/diagrams\//i, code: "smartart", lost: "dropped" },
+  { match: /^xl\/pivot/i, code: "pivot-tables", lost: "dropped" },
+  { match: /^xl\/externalLinks/i, code: "external-links", lost: "dropped" },
+  { match: /(^|\/)drawings\//i, code: "drawings", lost: "dropped" },
+  { match: /customXml/i, code: "custom-xml", lost: "dropped" },
+];
+
+function u16(bytes: Uint8Array, offset: number): number {
+  if (offset + 2 > bytes.length) return 0;
+  return bytes[offset]! | (bytes[offset + 1]! << 8);
+}
+
+function u32(bytes: Uint8Array, offset: number): number {
+  if (offset + 4 > bytes.length) return 0;
+  return (bytes[offset]! | (bytes[offset + 1]! << 8) | (bytes[offset + 2]! << 16) | (bytes[offset + 3]! << 24)) >>> 0;
+}
+
+function findEocd(bytes: Uint8Array): number {
+  const min = Math.max(0, bytes.length - 22 - 65535);
+  for (let i = bytes.length - 22; i >= min; i -= 1) {
+    if (u32(bytes, i) === EOCD) return i;
+  }
+  return -1;
+}
+
+/** Local-file names from the ZIP central directory — no inflate. */
+export function listZipEntryNames(bytes: Uint8Array): { readonly names: readonly string[]; readonly zip64: boolean } {
+  const eocd = findEocd(bytes);
+  if (eocd < 0) return { names: [], zip64: false };
+  const entries = u16(bytes, eocd + 10);
+  const cdOffset = u32(bytes, eocd + 16);
+  if (cdOffset === 0xffffffff || entries === 0xffff) return { names: [], zip64: true };
+  const names: string[] = [];
+  let off = cdOffset;
+  const n = Math.min(entries, HARD_ZIP_ENTRIES);
+  const decoder = new TextDecoder("utf-8", { fatal: false });
+  for (let i = 0; i < n; i += 1) {
+    if (off + 46 > bytes.length || u32(bytes, off) !== CDFH) break;
+    const nameLen = u16(bytes, off + 28);
+    const extraLen = u16(bytes, off + 30);
+    const commentLen = u16(bytes, off + 32);
+    const nameStart = off + 46;
+    const nameEnd = nameStart + nameLen;
+    if (nameEnd > bytes.length) break;
+    names.push(decoder.decode(bytes.subarray(nameStart, nameEnd)));
+    off = nameEnd + extraLen + commentLen;
+  }
+  return { names, zip64: false };
+}
+
+export function reportImportFidelity(bytes: Uint8Array, kind: DocumentKind): ImportFidelityReport {
+  const { names, zip64 } = listZipEntryNames(bytes);
+  const issues: ImportFidelityIssue[] = [];
+  if (zip64) issues.push({ code: "zip64", lost: "dropped" });
+  for (const part of names) {
+    if (issues.length >= HARD_FIDELITY_ISSUES) break;
+    const rule = RULES.find((candidate) => candidate.match.test(part));
+    if (!rule) continue;
+    issues.push({ code: rule.code, part, lost: rule.lost });
+  }
+  return {
+    kind,
+    issues: Object.freeze(issues.slice(0, HARD_FIDELITY_ISSUES)),
+    truncated: issues.length > HARD_FIDELITY_ISSUES || names.length >= HARD_ZIP_ENTRIES,
+  };
+}

package/work/src/documents/generate.ts

@@ -0,0 +1,96 @@
+import { type DocumentCaps, resolveDocumentCaps, validateByteCap, validateModelCaps } from "./caps.js";
+import { DocumentsFormatError } from "./errors.js";
+import { sha256Hex } from "./hash.js";
+import { validateDocumentModel } from "./model-schema.js";
+import type { DocumentsTelemetry } from "./telemetry.js";
+import { generateDocxBytes } from "./translate/docx.js";
+import { generatePptxBytes } from "./translate/pptx.js";
+import { generateXlsxBytes } from "./translate/xlsx.js";
+import type { DeckModel, DocModel, DocumentModel, SheetModel } from "./types.js";
+
+export type DocumentFormat = "docx" | "xlsx" | "pptx";
+
+export interface GenerateDocumentOptions {
+  /** Target OOXML output format. Must match document kind (doc->docx, sheet->xlsx, deck->pptx). */
+  readonly format: DocumentFormat;
+  /** Optional caps overrides. */
+  readonly caps?: DocumentCaps;
+  /** Optional telemetry seam hook for recording span metrics without text leaking. */
+  readonly telemetry?: DocumentsTelemetry;
+}
+
+export interface GenerateDocumentResult {
+  /** In-memory spec-compliant OOXML binary bytes (PK zip container). */
+  readonly bytes: Uint8Array;
+  /** 64-character lowercase SHA-256 hex digest of the output bytes. */
+  readonly contentHash: string;
+}
+
+/**
+ * Generates an in-memory, spec-compliant OOXML document (DOCX, XLSX, or PPTX)
+ * from a typed Prism Document Model.
+ *
+ * Enforces schema validation and element/byte caps before generation.
+ * Operates purely in memory with zero filesystem or network I/O.
+ */
+export async function generateDocument(model: DocumentModel, options: GenerateDocumentOptions): Promise<GenerateDocumentResult> {
+  const { format, caps: userCaps, telemetry } = options;
+
+  const span = telemetry?.startSpan("documents.generate", {
+    "documents.kind": model?.kind ?? "unknown",
+    "documents.format": format,
+  });
+
+  try {
+    if (model.kind === "doc" && format !== "docx") {
+      throw new DocumentsFormatError(`unsupported format "${format}" for doc model (expected "docx")`);
+    }
+    if (model.kind === "sheet" && format !== "xlsx") {
+      throw new DocumentsFormatError(`unsupported format "${format}" for sheet model (expected "xlsx")`);
+    }
+    if (model.kind === "deck" && format !== "pptx") {
+      throw new DocumentsFormatError(`unsupported format "${format}" for deck model (expected "pptx")`);
+    }
+
+    // 1. Trust boundary: validate model against Draft-07 schema and structural invariants
+    validateDocumentModel(model);
+
+    // 2. Resolve caps and check element counts before paying generation cost
+    const caps = resolveDocumentCaps(userCaps);
+    validateModelCaps(model, caps);
+
+    // 3. Translate and generate in-memory OOXML zip bytes
+    let bytes: Uint8Array;
+    switch (model.kind) {
+      case "doc":
+        bytes = generateDocxBytes(model as DocModel);
+        break;
+      case "sheet":
+        bytes = generateXlsxBytes(model as SheetModel);
+        break;
+      case "deck":
+        bytes = generatePptxBytes(model as DeckModel);
+        break;
+      default:
+        throw new DocumentsFormatError(`unsupported document kind: "${String((model as DocumentModel).kind)}"`);
+    }
+
+    // 4. Validate output byte length against maxBytes cap
+    validateByteCap(bytes.byteLength, caps);
+
+    // 5. Compute SHA-256 contentHash over the generated bytes
+    const contentHash = sha256Hex(bytes);
+
+    span?.setAttribute("documents.bytes", bytes.byteLength);
+
+    return {
+      bytes,
+      contentHash,
+    };
+  } catch (err) {
+    span?.recordError();
+    throw err;
+  } finally {
+    span?.end();
+  }
+}

package/work/src/documents/hash.ts

@@ -0,0 +1,8 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Computes a standard 64-character lowercase SHA-256 hex digest over binary bytes.
+ */
+export function sha256Hex(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}

package/work/src/documents/index.ts

@@ -0,0 +1,14 @@
+export * from "./caps.js";
+export * from "./diff.js";
+export * from "./errors.js";
+export * from "./fidelity.js";
+export * from "./generate.js";
+export * from "./hash.js";
+export * from "./model-schema.js";
+export * from "./parse.js";
+export * from "./patch.js";
+export * from "./patch-history.js";
+export * from "./preview.js";
+export * from "./preview-html.js";
+export * from "./telemetry.js";
+export * from "./types.js";