@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/session/import/embedded-offload.ts

@@ -0,0 +1,337 @@
+/**
+ * P8 Step 7 — load-time offload of `offloadable` embedded documents
+ * to host storage.
+ *
+ * Contract summary (architecture §P8):
+ *   - Runs once per `open()`. Iterates the embedded-document manifest
+ *     list produced by `collectEmbeddedDocuments`. Filters to entries
+ *     whose classifier-assigned `kind === "offloadable"`.
+ *   - If `hostAdapter.storeEmbeddedDocument` is present: materialise
+ *     each offloadable entry's bytes via the manifest's lazy `bytes()`
+ *     accessor, compute sha-256, call the adapter, and emit an
+ *     `EmbeddingOffloadEntry` record carrying everything needed for
+ *     export-time reconstitution (storage reference + inline-bytes
+ *     P3 fallback).
+ *   - If the adapter is absent, OR if `storeEmbeddedDocument` rejects /
+ *     throws for a specific entry, that entry silently degrades to
+ *     `store-only` semantics — no record is emitted, bytes stay on
+ *     the parent package via the existing opaque-preservation path.
+ *   - On reopen of a previously-offloaded package, the entries are
+ *     instead rehydrated from `customXml/item1.xml` under the
+ *     `bw:embeddings` namespace; see `hydrateOffloadEntriesFromPayload`.
+ *
+ * Scope of this module: load-side only. The export-side mirror
+ * (writes customXml namespace, calls `loadEmbeddedDocument`, rebuilds
+ * package parts) lives at `src/session/export/embedded-reconstitute.ts`.
+ *
+ * P6 clean — imports from api/**, io/** (opc + ooxml), model/**,
+ * preservation/**, shared session utilities only.
+ */
+
+import type {
+  EditorHostAdapter,
+  EmbeddedDocumentManifestLike,
+  StorageReference,
+} from "../../api/public-types.ts";
+import {
+  decodeBytesBase64,
+  encodeBytesBase64,
+  sha256Hex,
+} from "../../io/source-package-provenance.ts";
+import type { EmbeddedDocumentManifest } from "../types.ts";
+import type { EditorStatePayload } from "../../io/ooxml/workflow-payload.ts";
+
+/**
+ * Full record for a single offloaded embedded document. Carries the
+ * metadata the export path needs to rebuild the package part when
+ * the host's `loadEmbeddedDocument` succeeds, AND the inline-bytes
+ * base64 fallback that keeps export byte-identical when the host
+ * returns null / throws.
+ */
+export interface EmbeddingOffloadEntry {
+  /** Manifest id — stable across open/export (content-fingerprint). */
+  readonly embeddedDocId: string;
+  /** Relationship id the source document uses for this embedding. */
+  readonly relationshipId: string;
+  /** Absolute OPC part path the embedding was extracted from. */
+  readonly sourcePartPath: string;
+  /** OPC content type. Preserved verbatim across round-trip. */
+  readonly contentType: string;
+  /** SHA-256 hex digest of the embedding bytes. */
+  readonly sha256: string;
+  /** Opaque storage handle the host returned. */
+  readonly storageReference: StorageReference;
+  /**
+   * Base64-encoded copy of the embedding bytes. Authoritative P3
+   * fallback — every entry carries this regardless of whether the
+   * host implemented `storeEmbeddedDocument`, so export reconstitution
+   * never fails on storage unavailability.
+   */
+  readonly inlineBytes: string;
+}
+
+/**
+ * Output of `processEmbeddedOffload`. `entries` is empty when no
+ * adapter is available OR when zero offloadable manifests were found
+ * OR when every offloadable adapter call failed.
+ */
+export interface EmbeddedOffloadResult {
+  readonly entries: readonly EmbeddingOffloadEntry[];
+  /**
+   * Absolute part paths of every successfully offloaded embedding.
+   * Passed into `buildImportPreservation`'s `ownedPartPaths` list so
+   * those parts are EXCLUDED from preservation — the export
+   * reconstitute path is the sole writer for them.
+   */
+  readonly ownedPartPaths: readonly string[];
+}
+
+/**
+ * Parameters accepted by `processEmbeddedOffload`.
+ */
+export interface ProcessEmbeddedOffloadParams {
+  /** Document id passed to the host adapter. */
+  readonly parentDocumentId: string;
+  /** Full manifest list from `collectEmbeddedDocuments`. */
+  readonly manifests: readonly EmbeddedDocumentManifest[];
+  /** Host adapter; `undefined` skips offload entirely. */
+  readonly hostAdapter: EditorHostAdapter | undefined;
+  /**
+   * Lookup from manifest relationship id → absolute OPC part path
+   * (as resolved via `resolveRelationshipTarget`). Allows this module
+   * to stay decoupled from `part-manifest.ts` resolution logic —
+   * the loader already resolved every relationship it walked.
+   */
+  readonly resolvePartPath: (relationshipId: string) => string | undefined;
+  /** OPC content type for each part path. */
+  readonly resolveContentType: (partPath: string) => string | undefined;
+}
+
+/**
+ * Run the load-time offload pass. Safe to call with any of the
+ * parameters in a "disabling" shape — no adapter, empty manifests,
+ * zero offloadable entries — all return `{ entries: [], ownedPartPaths: [] }`.
+ *
+ * Swallowed diagnostics: `storeEmbeddedDocument` rejections / throws
+ * are caught per-entry. The offending manifest silently falls back to
+ * `store-only` semantics. Callers that want visibility should scan
+ * the returned entry list against the input manifests and diff.
+ */
+export async function processEmbeddedOffload(
+  params: ProcessEmbeddedOffloadParams,
+): Promise<EmbeddedOffloadResult> {
+  const { parentDocumentId, manifests, hostAdapter, resolvePartPath, resolveContentType } = params;
+  if (!hostAdapter?.storeEmbeddedDocument) {
+    return EMPTY_RESULT;
+  }
+  const offloadables = manifests.filter((m) => m.kind === "offloadable");
+  if (offloadables.length === 0) {
+    return EMPTY_RESULT;
+  }
+
+  const entries: EmbeddingOffloadEntry[] = [];
+  const ownedPartPaths: string[] = [];
+  for (const manifest of offloadables) {
+    const sourcePartPath = resolvePartPath(manifest.relationshipId);
+    if (!sourcePartPath) continue; // Shouldn't happen — defensive.
+    let bytes: Uint8Array;
+    try {
+      bytes = manifest.bytes();
+    } catch {
+      // Lazy accessor failed — fall back to store-only. The
+      // preservation path will still carry the bytes (the source
+      // package part is untouched).
+      continue;
+    }
+    const contentType = resolveContentType(sourcePartPath) ?? "application/octet-stream";
+    const sha = sha256Hex(bytes);
+    const manifestLike: EmbeddedDocumentManifestLike = {
+      id: manifest.id,
+      kind: manifest.kind,
+      size: manifest.size,
+      relationshipId: manifest.relationshipId,
+      ...(manifest.progId !== undefined ? { progId: manifest.progId } : {}),
+      ...(manifest.mimeType !== undefined ? { mimeType: manifest.mimeType } : {}),
+      ...(manifest.filename !== undefined ? { filename: manifest.filename } : {}),
+    };
+    let hostRef: StorageReference;
+    try {
+      hostRef = await hostAdapter.storeEmbeddedDocument({
+        parentDocumentId,
+        embedded: manifestLike,
+        bytes,
+      });
+    } catch {
+      // Host rejected — this specific entry falls back to store-only.
+      // Other offloadable entries in the same package are unaffected.
+      continue;
+    }
+    // Defensive: validate the adapter's return shape. A host could
+    // return `undefined`, `null`, or a malformed object; TypeScript's
+    // `Promise<StorageReference>` annotation is a compile-time
+    // contract, not a runtime check. On malformed returns, fall back
+    // to store-only for this entry.
+    if (
+      typeof hostRef !== "object" ||
+      hostRef === null ||
+      typeof hostRef.providerId !== "string" ||
+      typeof hostRef.handle !== "string"
+    ) {
+      continue;
+    }
+    // Per the `StorageReference.sha256` contract in `public-types.ts`:
+    // the session computes the sha; the reference round-trips it
+    // unchanged. Override whatever the host returned with the value
+    // we computed from the authoritative bytes so tamper-detection at
+    // rehydrate time compares against the session's own measurement.
+    const storageReference: StorageReference = {
+      providerId: hostRef.providerId,
+      handle: hostRef.handle,
+      sha256: sha,
+    };
+    entries.push({
+      embeddedDocId: manifest.id,
+      relationshipId: manifest.relationshipId,
+      sourcePartPath,
+      contentType,
+      sha256: sha,
+      storageReference,
+      inlineBytes: encodeBytesBase64(bytes),
+    });
+    ownedPartPaths.push(sourcePartPath);
+  }
+  return { entries, ownedPartPaths };
+}
+
+/**
+ * Rehydrate offload entries from a `bw:embeddings` customXml payload
+ * the session read during `parseWorkflowPayloadEnvelopeFromPackage`.
+ * Returns an empty result when the payload has no `embeddings`
+ * namespace entry, or when the entry's inline JSON is malformed.
+ *
+ * Used on REOPEN: when a previously-offloaded package is opened
+ * again, we don't re-run the adapter — we trust the customXml record.
+ * The reconstitute pass at export uses these entries exactly as if
+ * they had come from a fresh offload pass.
+ */
+export function hydrateOffloadEntriesFromPayload(
+  payload: EditorStatePayload | undefined,
+): EmbeddedOffloadResult {
+  if (!payload) return EMPTY_RESULT;
+  const entry = payload.entries.find((e) => e.namespace === "embeddings");
+  if (!entry || entry.inline === undefined || entry.malformedInline) {
+    return EMPTY_RESULT;
+  }
+  const parsed = parseEmbeddingsInline(entry.inline);
+  if (!parsed) return EMPTY_RESULT;
+  return {
+    entries: parsed,
+    ownedPartPaths: parsed.map((e) => e.sourcePartPath),
+  };
+}
+
+/**
+ * Schema the `bw:embeddings` inline JSON uses. Versioned so future
+ * field additions remain non-breaking. Current version: `1`.
+ */
+export interface EmbeddingsInlineSchema {
+  readonly version: 1;
+  readonly entries: readonly EmbeddingOffloadEntry[];
+}
+
+/**
+ * Serialise the collected offload entries into the JSON shape the
+ * customXml `bw:embeddings` inline block expects.
+ */
+export function buildEmbeddingsInlinePayload(
+  entries: readonly EmbeddingOffloadEntry[],
+): EmbeddingsInlineSchema {
+  return { version: 1, entries };
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+const EMPTY_RESULT: EmbeddedOffloadResult = Object.freeze({
+  entries: Object.freeze([]) as readonly EmbeddingOffloadEntry[],
+  ownedPartPaths: Object.freeze([]) as readonly string[],
+});
+
+// Base64 encode/decode reach the cross-runtime helpers in
+// `src/io/source-package-provenance.ts` — those handle both Node
+// (Buffer) and browser (btoa/atob) contexts. Direct call; the earlier
+// local `encodeBase64` alias was unnecessary indirection.
+
+function parseEmbeddingsInline(
+  inline: unknown,
+): EmbeddingOffloadEntry[] | undefined {
+  if (
+    typeof inline !== "object" ||
+    inline === null ||
+    !("entries" in inline) ||
+    !Array.isArray((inline as { entries: unknown }).entries)
+  ) {
+    return undefined;
+  }
+  // Forward-compat: reject unknown schema versions rather than
+  // attempting a best-effort parse that could silently drop fields a
+  // future schema depends on. `version` is absent in a malformed
+  // payload (parseEmbeddingsInline rejects below via entry-shape
+  // checks anyway); a non-1 version is a genuine forward-compat
+  // break that should surface as "no offload entries available"
+  // rather than a quiet partial rehydration.
+  const version = (inline as { version?: unknown }).version;
+  if (version !== undefined && version !== 1) {
+    return undefined;
+  }
+  const raw = (inline as { entries: unknown[] }).entries;
+  const out: EmbeddingOffloadEntry[] = [];
+  for (const item of raw) {
+    if (typeof item !== "object" || item === null) continue;
+    const r = item as Record<string, unknown>;
+    if (
+      typeof r.embeddedDocId !== "string" ||
+      typeof r.relationshipId !== "string" ||
+      typeof r.sourcePartPath !== "string" ||
+      typeof r.contentType !== "string" ||
+      typeof r.sha256 !== "string" ||
+      typeof r.inlineBytes !== "string" ||
+      typeof r.storageReference !== "object" ||
+      r.storageReference === null
+    ) {
+      continue;
+    }
+    const ref = r.storageReference as Record<string, unknown>;
+    if (
+      typeof ref.providerId !== "string" ||
+      typeof ref.handle !== "string" ||
+      typeof ref.sha256 !== "string"
+    ) {
+      continue;
+    }
+    out.push({
+      embeddedDocId: r.embeddedDocId,
+      relationshipId: r.relationshipId,
+      sourcePartPath: r.sourcePartPath,
+      contentType: r.contentType,
+      sha256: r.sha256,
+      inlineBytes: r.inlineBytes,
+      storageReference: {
+        providerId: ref.providerId,
+        handle: ref.handle,
+        sha256: ref.sha256,
+      },
+    });
+  }
+  return out;
+}
+
+/**
+ * Decode the base64 inline-bytes fallback back into raw bytes. Used
+ * by the export reconstitute path when `loadEmbeddedDocument` is
+ * unavailable or returns null.
+ */
+export function decodeInlineBytes(base64: string): Uint8Array {
+  return decodeBytesBase64(base64);
+}

package/src/session/import/import-diagnostics.ts

@@ -0,0 +1,69 @@
+/**
+ * Typed warning-record builders for the session import layer.
+ *
+ * Slice 3b of refactor/01 package-session. Extracted from
+ * src/io/docx-session.ts (duplicate inline `.map()` transforms at
+ * the diagnostics assembly site in both the sync and async load paths).
+ *
+ * Each function maps a parse-layer diagnostic array into the
+ * `CanonicalDocument.diagnostics.warnings` record shape so call sites
+ * stay concise and IDs stay consistent.
+ *
+ * Contract P6 clean. Depends only on model types and the two parser
+ * modules that define the input diagnostic shapes.
+ */
+
+import type { CanonicalDocument } from "../../model/canonical-document.ts";
+import type { RevisionImportDiagnostic } from "../../io/ooxml/parse-revisions.ts";
+import type { CommentImportDiagnostic } from "../../io/ooxml/parse-comments.ts";
+
+/** Warning shape carried on `CanonicalDocument.diagnostics.warnings`. */
+type CanonicalWarning = CanonicalDocument["diagnostics"]["warnings"][number];
+
+/**
+ * Map main-document revision diagnostics into stable warning records.
+ * Uses `diagnostic:revision-import-N` / `warning:revision-import-<id>`
+ * naming so IDs are deterministic across serialization round-trips.
+ */
+export function mapRevisionDiagnosticsToWarnings(
+  diagnostics: readonly RevisionImportDiagnostic[],
+): CanonicalWarning[] {
+  return diagnostics.map((diagnostic, index) => ({
+    diagnosticId: `diagnostic:revision-import-${index + 1}`,
+    warningId: `warning:revision-import-${diagnostic.revisionId}`,
+    source: "review" as const,
+    message: diagnostic.message,
+  }));
+}
+
+/**
+ * Map story-part (header / footer) revision diagnostics into stable
+ * warning records. Uses `diagnostic:story-revision-import-N` /
+ * `warning:story-revision-import-<id>` naming to avoid colliding with
+ * the main-document revision warnings above.
+ */
+export function mapStoryRevisionDiagnosticsToWarnings(
+  diagnostics: readonly RevisionImportDiagnostic[],
+): CanonicalWarning[] {
+  return diagnostics.map((diagnostic, index) => ({
+    diagnosticId: `diagnostic:story-revision-import-${index + 1}`,
+    warningId: `warning:story-revision-import-${diagnostic.revisionId}`,
+    source: "review" as const,
+    message: diagnostic.message,
+  }));
+}
+
+/**
+ * Map comment-parse diagnostics into stable warning records. Uses
+ * `diagnostic:comment-import-N` / `warning:comment-import-<id>` naming.
+ */
+export function mapCommentDiagnosticsToWarnings(
+  diagnostics: readonly CommentImportDiagnostic[],
+): CanonicalWarning[] {
+  return diagnostics.map((diagnostic, index) => ({
+    diagnosticId: `diagnostic:comment-import-${index + 1}`,
+    warningId: `warning:comment-import-${diagnostic.commentId}`,
+    source: "review" as const,
+    message: diagnostic.message,
+  }));
+}