@beyondwork/docx-react-component 1.0.41 → 1.0.42

package/src/io/ooxml/workflow-payload-validator.ts

@@ -0,0 +1,271 @@
+/**
+ * Local-path validator for bw:workflowPayload 1.0 / 1.1.
+ *
+ * This is a structural sanity check that runs inline on every import.
+ * It does NOT replace the Railway OOXML validator — that one checks
+ * package-level concerns (part types, relationship sanity, Word-spec
+ * compliance).  This validator catches malformed bw:workflowPayload
+ * content that the parser would silently strip.  Results surface to
+ * callers so tooling can log, display, or assert on them.
+ *
+ * Spec: docs/reference/bw-schema-spec.md §8.2.
+ */
+
+export type ValidatorIssueCode =
+  | "unknown_enum_value"
+  | "external_entry_missing_ref"
+  | "external_entry_body_ignored"
+  | "external_field_missing_ref"
+  | "external_field_body_ignored"
+  | "internal_entry_unexpected_storage_ref"
+  | "internal_field_unexpected_storage_ref"
+  | "unsupported_version";
+
+export type ValidatorIssueSeverity = "error" | "warning";
+
+export interface ValidatorIssue {
+  code: ValidatorIssueCode;
+  path: string; // e.g. "bw:entry[@key='e1']"
+  severity: ValidatorIssueSeverity;
+  value?: string; // the invalid value when relevant
+  detail?: string; // optional extra context
+}
+
+const OVERLAY_PERSISTENCE_VALUES = ["internal", "external"] as const;
+const SCOPE_PERSISTENCE_VALUES = ["internal", "external", "inherit"] as const;
+
+export function validateWorkflowPayloadEnvelope(xml: string): ValidatorIssue[] {
+  const issues: ValidatorIssue[] = [];
+
+  // Root version check.
+  const versionMatch = xml.match(/<bw:workflowPayload\b[^>]*\sversion="([^"]+)"/u);
+  if (versionMatch && !/^1\.[0-9]+$/.test(versionMatch[1])) {
+    issues.push({
+      code: "unsupported_version",
+      path: "bw:workflowPayload/@version",
+      value: versionMatch[1],
+      severity: "warning",
+    });
+  }
+
+  // Overlay-level metadataPersistence.
+  const overlayMatch = xml.match(/<bw:workflowOverlay\b([^>]*)>/u);
+  let overlayEnum: "internal" | "external" | undefined;
+  if (overlayMatch) {
+    const attrs = parseAttrs(overlayMatch[1]);
+    if (attrs.metadataPersistence !== undefined) {
+      if (
+        !(OVERLAY_PERSISTENCE_VALUES as readonly string[]).includes(
+          attrs.metadataPersistence,
+        )
+      ) {
+        issues.push({
+          code: "unknown_enum_value",
+          path: "bw:workflowOverlay/@metadataPersistence",
+          value: attrs.metadataPersistence,
+          severity: "warning",
+        });
+      } else {
+        overlayEnum = attrs.metadataPersistence as "internal" | "external";
+      }
+    }
+  }
+
+  // Each scope + its fields.
+  for (const scope of findAll(xml, /<bw:scope\b([^>]*?)>([\s\S]*?)<\/bw:scope>/gu)) {
+    const scopeAttrs = parseAttrs(scope.attrs);
+    const scopeId = scopeAttrs.id ?? "?";
+    let scopePersistence: string | undefined = scopeAttrs.metadataPersistence;
+    if (scopePersistence !== undefined) {
+      if (
+        !(SCOPE_PERSISTENCE_VALUES as readonly string[]).includes(scopePersistence)
+      ) {
+        issues.push({
+          code: "unknown_enum_value",
+          path: `bw:scope[@id='${scopeId}']/@metadataPersistence`,
+          value: scopePersistence,
+          severity: "warning",
+        });
+        scopePersistence = undefined;
+      }
+    }
+
+    // <bw:field>, two forms: self-closing and with body.
+    for (const field of findFields(scope.body)) {
+      const fieldAttrs = parseAttrs(field.attrs);
+      const fieldKey = fieldAttrs.key ?? "?";
+
+      let fieldPersistence: string | undefined = fieldAttrs.metadataPersistence;
+      if (
+        fieldPersistence !== undefined &&
+        !(SCOPE_PERSISTENCE_VALUES as readonly string[]).includes(fieldPersistence)
+      ) {
+        issues.push({
+          code: "unknown_enum_value",
+          path: `bw:scope[@id='${scopeId}']/bw:field[@key='${fieldKey}']/@metadataPersistence`,
+          value: fieldPersistence,
+          severity: "warning",
+        });
+        fieldPersistence = undefined;
+      }
+
+      const effective = resolveEffective({
+        overlay: overlayEnum,
+        scope: scopePersistence,
+        field: fieldPersistence,
+      });
+      const hasRef = Boolean(fieldAttrs.storageRef);
+      const hasBody = field.body.trim().length > 0;
+
+      if (effective === "external") {
+        if (!hasRef) {
+          issues.push({
+            code: "external_field_missing_ref",
+            path: `bw:scope[@id='${scopeId}']/bw:field[@key='${fieldKey}']`,
+            severity: "error",
+          });
+        }
+        if (hasBody) {
+          issues.push({
+            code: "external_field_body_ignored",
+            path: `bw:scope[@id='${scopeId}']/bw:field[@key='${fieldKey}']`,
+            severity: "warning",
+          });
+        }
+      } else if (effective === "internal" && hasRef) {
+        // Internal-mode fields carry their value inline.  A `storageRef` on
+        // an internal field is a stale pointer from a persistence-mode
+        // downgrade and will confuse hosts that branch on its presence.
+        issues.push({
+          code: "internal_field_unexpected_storage_ref",
+          path: `bw:scope[@id='${scopeId}']/bw:field[@key='${fieldKey}']`,
+          severity: "warning",
+        });
+      }
+    }
+  }
+
+  // Top-level entries (bw:metadata body, outside scopes).
+  // These resolve against overlay-only (no scope context available unless
+  // the entry carries its own `scope="scope:{id}"` attribute, in which case
+  // a matching scope's override would apply — we keep this simple and just
+  // use the overlay default for entries).
+  for (const entry of findEntries(xml)) {
+    const entryAttrs = parseAttrs(entry.attrs);
+    const entryKey = entryAttrs.key ?? "?";
+
+    // Definition rows (key="definition.*") are schema descriptors, not data
+    // entries.  Their body is always the human-readable label (per §4.1) and
+    // they are never subject to external-persistence rules (§4.3 applies only
+    // to data rows, §4.2).  Skip persistence checks for them.
+    if (entryKey.startsWith("definition.")) {
+      continue;
+    }
+
+    let entryPersistence: string | undefined = entryAttrs.metadataPersistence;
+    if (
+      entryPersistence !== undefined &&
+      !(SCOPE_PERSISTENCE_VALUES as readonly string[]).includes(entryPersistence)
+    ) {
+      issues.push({
+        code: "unknown_enum_value",
+        path: `bw:entry[@key='${entryKey}']/@metadataPersistence`,
+        value: entryPersistence,
+        severity: "warning",
+      });
+      entryPersistence = undefined;
+    }
+
+    const effective = resolveEffective({
+      overlay: overlayEnum,
+      scope: undefined,
+      field: entryPersistence,
+    });
+    const hasRef = Boolean(entryAttrs.storageRef);
+    const hasBody = entry.body.trim().length > 0;
+
+    if (effective === "external") {
+      if (!hasRef) {
+        issues.push({
+          code: "external_entry_missing_ref",
+          path: `bw:entry[@key='${entryKey}']`,
+          severity: "error",
+        });
+      }
+      if (hasBody) {
+        issues.push({
+          code: "external_entry_body_ignored",
+          path: `bw:entry[@key='${entryKey}']`,
+          severity: "warning",
+        });
+      }
+    } else if (effective === "internal" && hasRef) {
+      // Internal-mode entries carry their value inline.  A `storageRef` on
+      // an internal entry is a stale pointer from a persistence-mode
+      // downgrade and will confuse hosts that branch on its presence.
+      issues.push({
+        code: "internal_entry_unexpected_storage_ref",
+        path: `bw:entry[@key='${entryKey}']`,
+        severity: "warning",
+      });
+    }
+  }
+
+  return issues;
+}
+
+function parseAttrs(source: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const m of source.matchAll(/(\w+)="([^"]*)"/gu)) {
+    out[m[1]] = m[2];
+  }
+  return out;
+}
+
+function* findAll(
+  xml: string,
+  re: RegExp,
+): Generator<{ attrs: string; body: string }> {
+  for (const m of xml.matchAll(re)) {
+    yield { attrs: m[1] ?? "", body: m[2] ?? "" };
+  }
+}
+
+/**
+ * Emits each `<bw:field>` in the scope body, handling both self-closing
+ * and body-bearing forms.
+ */
+function* findFields(
+  scopeBody: string,
+): Generator<{ attrs: string; body: string }> {
+  // Match both <bw:field .../> and <bw:field ...>body</bw:field>
+  const re = /<bw:field\b([^>]*?)(?:\/>|>([\s\S]*?)<\/bw:field>)/gu;
+  for (const m of scopeBody.matchAll(re)) {
+    yield { attrs: m[1] ?? "", body: m[2] ?? "" };
+  }
+}
+
+/**
+ * Emits each top-level `<bw:entry>` (inside `<bw:metadata>`), handling
+ * both self-closing and body-bearing forms.  Scope-internal entries
+ * are handled by findFields — this only looks at the flat metadata list.
+ */
+function* findEntries(
+  xml: string,
+): Generator<{ attrs: string; body: string }> {
+  const re = /<bw:entry\b([^>]*?)(?:\/>|>([\s\S]*?)<\/bw:entry>)/gu;
+  for (const m of xml.matchAll(re)) {
+    yield { attrs: m[1] ?? "", body: m[2] ?? "" };
+  }
+}
+
+function resolveEffective(input: {
+  overlay?: "internal" | "external";
+  scope?: string;
+  field?: string;
+}): "internal" | "external" {
+  if (input.field === "internal" || input.field === "external") return input.field;
+  if (input.scope === "internal" || input.scope === "external") return input.scope;
+  if (input.overlay === "external") return "external";
+  return "internal";
+}

package/src/io/ooxml/workflow-payload.ts

@@ -12,6 +12,29 @@ import type {
   WorkflowScope,
   WorkflowWorkItem,
 } from "../../api/public-types.ts";
+import {
+  validateWorkflowPayloadEnvelope,
+  type ValidatorIssue,
+} from "./workflow-payload-validator.ts";
+
+// ---------------------------------------------------------------------------
+// Schema 1.1 parser helpers (fail-closed per spec §8.2)
+// ---------------------------------------------------------------------------
+
+function parseClosedEnum<T extends string>(
+  raw: string | undefined,
+  allowed: readonly T[],
+): T | undefined {
+  if (raw === undefined) return undefined;
+  return (allowed as readonly string[]).includes(raw) ? (raw as T) : undefined;
+}
+
+function parseNonNegativeInt(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 0) return undefined;
+  return n;
+}
 
 export const WORKFLOW_PAYLOAD_PART_PATH = "/customXml/item1.xml";
 export const WORKFLOW_PAYLOAD_ITEM_PROPS_PART_PATH = "/customXml/itemProps1.xml";
@@ -39,6 +62,7 @@ type EmbeddedWorkflowPayloadDescriptor = {
 export interface WorkflowPayloadEnvelope {
   workflowMetadata: WorkflowMetadataSnapshot;
   workflowOverlay?: WorkflowOverlay;
+  validatorIssues?: readonly ValidatorIssue[];
 }
 
 export function getDocumentBackedWorkflowMetadata(
@@ -144,7 +168,8 @@ export function parseWorkflowPayloadEnvelopeFromPackage(
   }
 
   const xml = decodeUtf8(payloadPart.bytes);
-  const entryMatches = [...xml.matchAll(/<bw:entry\b([^>]*)>([\s\S]*?)<\/bw:entry>/g)];
+  // Match both self-closing (<bw:entry .../>) and body-bearing (<bw:entry ...>body</bw:entry>)
+  const entryMatches = [...xml.matchAll(/<bw:entry\b([^>]*)(?:\/>|>([\s\S]*?)<\/bw:entry>)/g)];
   const definitions: WorkflowMetadataDefinition[] = [];
   const entries: WorkflowMetadataEntry[] = [];
 
@@ -183,6 +208,14 @@ export function parseWorkflowPayloadEnvelopeFromPackage(
     if (!entryId || !metadataId) {
       continue;
     }
+
+    const entryMetadataPersistence = parseClosedEnum(
+      attributes.metadataPersistence,
+      ["internal", "external", "inherit"] as const,
+    );
+    const entryStorageRef = attributes.storageRef;
+    const entryMetadataVersion = parseNonNegativeInt(attributes.metadataVersion);
+
     entries.push({
       entryId,
       metadataId,
@@ -198,18 +231,62 @@ export function parseWorkflowPayloadEnvelopeFromPackage(
       ...(attributes.scope?.startsWith("workItem:")
         ? { workItemId: attributes.scope.slice("workItem:".length) }
         : {}),
+      ...(entryMetadataPersistence !== undefined ? { metadataPersistence: entryMetadataPersistence } : {}),
+      ...(entryStorageRef !== undefined ? { storageRef: entryStorageRef } : {}),
+      ...(entryMetadataVersion !== undefined ? { metadataVersion: entryMetadataVersion } : {}),
     });
   }
 
+  const validatorIssues = validateWorkflowPayloadEnvelope(xml);
   return {
     workflowMetadata: {
       definitions,
       entries,
     },
     workflowOverlay: parseWorkflowOverlay(xml),
+    ...(validatorIssues.length > 0 ? { validatorIssues } : {}),
   };
 }
 
+function needsSchemaV11(input: {
+  workflowMetadata: WorkflowMetadataSnapshot;
+  workflowOverlay?: WorkflowOverlay;
+}): boolean {
+  if (input.workflowOverlay?.metadataPersistence !== undefined) {
+    return true;
+  }
+  if (
+    input.workflowOverlay?.scopes?.some(
+      (s) => s.metadataPersistence !== undefined,
+    )
+  ) {
+    return true;
+  }
+  if (
+    input.workflowOverlay?.scopes?.some((s) =>
+      s.metadata?.some(
+        (f) =>
+          f.metadataPersistence !== undefined ||
+          f.storageRef !== undefined ||
+          f.metadataVersion !== undefined,
+      ),
+    )
+  ) {
+    return true;
+  }
+  if (
+    input.workflowMetadata.entries.some(
+      (e) =>
+        e.metadataPersistence !== undefined ||
+        e.storageRef !== undefined ||
+        e.metadataVersion !== undefined,
+    )
+  ) {
+    return true;
+  }
+  return false;
+}
+
 function buildPayloadXml(input: {
   descriptor: EmbeddedWorkflowPayloadDescriptor;
   createdAt: string;
@@ -219,6 +296,8 @@ function buildPayloadXml(input: {
   workflowOverlay?: WorkflowOverlay;
   preservedExtensionsXml: string;
 }): string {
+  const schemaVersion = needsSchemaV11(input) ? "1.1" : "1.0";
+
   const definitionEntriesXml = input.workflowMetadata.definitions
     .map((definition) => [
       `<bw:entry`,
@@ -237,7 +316,7 @@ function buildPayloadXml(input: {
       const serializedValue = serializeWorkflowMetadataValue(entry.value);
       const storyTargetAttributes = serializeWorkflowStoryTarget(entry.storyTarget);
 
-      return [
+      const baseAttrs = [
         `<bw:entry`,
         ` key="${escapeXml(entry.entryId)}"`,
         ` metadataId="${escapeXml(entry.metadataId)}"`,
@@ -245,8 +324,24 @@ function buildPayloadXml(input: {
         ` valueType="${escapeXml(serializedValue.type)}"`,
         ` scope="${escapeXml(entry.scopeId ? `scope:${entry.scopeId}` : entry.workItemId ? `workItem:${entry.workItemId}` : "document")}"`,
         storyTargetAttributes,
-        `>${escapeXml(serializedValue.text)}</bw:entry>`,
+        entry.metadataPersistence && entry.metadataPersistence !== "inherit"
+          ? ` metadataPersistence="${escapeXml(entry.metadataPersistence)}"`
+          : "",
+        entry.metadataPersistence === "external" && entry.storageRef
+          ? ` storageRef="${escapeXml(entry.storageRef)}"`
+          : "",
+        typeof entry.metadataVersion === "number" &&
+        Number.isInteger(entry.metadataVersion) &&
+        entry.metadataVersion >= 0
+          ? ` metadataVersion="${entry.metadataVersion.toString()}"`
+          : "",
       ].join("");
+
+      if (entry.metadataPersistence === "external") {
+        return `${baseAttrs}/>`;
+      }
+
+      return `${baseAttrs}>${escapeXml(serializedValue.text)}</bw:entry>`;
     })
     .filter((value) => value.length > 0)
     .join("\n");
@@ -258,7 +353,7 @@ function buildPayloadXml(input: {
 
   return [
     `<?xml version="1.0" encoding="UTF-8"?>`,
-    `<bw:workflowPayload xmlns:bw="urn:beyondwork:workflow-payload:1" version="1.0" payloadId="${escapeXml(input.descriptor.payloadId)}" itemId="${escapeXml(input.descriptor.itemId)}" documentId="${escapeXml(input.descriptor.documentId)}" createdAt="${escapeXml(input.createdAt)}" updatedAt="${escapeXml(input.updatedAt)}">`,
+    `<bw:workflowPayload xmlns:bw="urn:beyondwork:workflow-payload:1" version="${schemaVersion}" payloadId="${escapeXml(input.descriptor.payloadId)}" itemId="${escapeXml(input.descriptor.itemId)}" documentId="${escapeXml(input.descriptor.documentId)}" createdAt="${escapeXml(input.createdAt)}" updatedAt="${escapeXml(input.updatedAt)}">`,
     `  <bw:manifest>`,
     `    <bw:producer name="@beyondwork/docx-react-component" version="${escapeXml(input.producerVersion)}" />`,
     `    <bw:compatibility rebindMode="best-effort" preserveUnknownExtensions="true" />`,
@@ -357,6 +452,9 @@ function buildWorkblockExtensionXml(workflowOverlay: WorkflowOverlay | undefined
       workflowOverlay.activeWorkItemId
         ? ` activeWorkItemId="${escapeXml(workflowOverlay.activeWorkItemId)}"`
         : "",
+      workflowOverlay.metadataPersistence
+        ? ` metadataPersistence="${escapeXml(workflowOverlay.metadataPersistence)}"`
+        : "",
       `>`,
     ].join(""),
     `  <bw:workItems>`,
@@ -380,6 +478,9 @@ function buildWorkflowScopeXml(scope: WorkflowScope): string {
     scope.workItemId ? ` workItemRef="${escapeXml(scope.workItemId)}"` : "",
     scope.label ? ` label="${escapeXml(scope.label)}"` : "",
     scope.domain ? ` domain="${escapeXml(scope.domain)}"` : "",
+    scope.metadataPersistence && scope.metadataPersistence !== "inherit"
+      ? ` metadataPersistence="${escapeXml(scope.metadataPersistence)}"`
+      : "",
     `>`,
     indentLines(buildWorkflowAnchorXml(scope.anchor, scope.storyTarget), 2),
     scopeMetadataXml ? indentLines(scopeMetadataXml, 2) : "",
@@ -397,12 +498,28 @@ function buildWorkflowScopeMetadataXml(scopeMetadata: WorkflowScope["metadata"])
       scopeMetadata
         .map((field) => {
           const serialized = serializeWorkflowScopeMetadataValue(field.valueType, field.value);
-          return [
+          const baseAttrs = [
             `<bw:field`,
             ` key="${escapeXml(field.key)}"`,
             serialized.valueType ? ` type="${escapeXml(serialized.valueType)}"` : "",
-            `>${escapeXml(serialized.text)}</bw:field>`,
+            field.metadataPersistence && field.metadataPersistence !== "inherit"
+              ? ` metadataPersistence="${escapeXml(field.metadataPersistence)}"`
+              : "",
+            field.metadataPersistence === "external" && field.storageRef
+              ? ` storageRef="${escapeXml(field.storageRef)}"`
+              : "",
+            typeof field.metadataVersion === "number" &&
+            Number.isInteger(field.metadataVersion) &&
+            field.metadataVersion >= 0
+              ? ` metadataVersion="${field.metadataVersion.toString()}"`
+              : "",
           ].join("");
+
+          if (field.metadataPersistence === "external") {
+            return `${baseAttrs}/>`;
+          }
+
+          return `${baseAttrs}>${escapeXml(serialized.text)}</bw:field>`;
         })
         .join("\n"),
       2,
@@ -571,11 +688,17 @@ function parseWorkflowOverlay(xml: string): WorkflowOverlay | undefined {
     .map((match) => parseWorkflowWorkItem(match[1] ?? "", match[2] ?? ""))
     .filter((item): item is WorkflowWorkItem => item !== null);
 
+  const overlayMetadataPersistence = parseClosedEnum(
+    overlayAttributes.metadataPersistence,
+    ["internal", "external"] as const,
+  );
+
   return {
     overlayVersion: (overlayAttributes.overlayVersion as WorkflowOverlay["overlayVersion"]) ?? "workflow-overlay/1",
     activeWorkItemId: overlayAttributes.activeWorkItemId ?? null,
     scopes,
     ...(workItems.length > 0 ? { workItems } : {}),
+    ...(overlayMetadataPersistence !== undefined ? { metadataPersistence: overlayMetadataPersistence } : {}),
   };
 }
 
@@ -588,6 +711,11 @@ function parseWorkflowScope(attributesSource: string, body: string): WorkflowSco
   const anchor = anchorMatch
     ? parseWorkflowOverlayAnchor(anchorMatch[1] ?? "", anchorMatch[2] ?? "")
     : createDefaultRangeAnchor(0, 0);
+  const scopeMetadataPersistence = parseClosedEnum(
+    attributes.metadataPersistence,
+    ["internal", "external", "inherit"] as const,
+  );
+
   return {
     scopeId: attributes.id,
     version: attributes.version !== undefined ? Number(attributes.version) : undefined,
@@ -598,6 +726,7 @@ function parseWorkflowScope(attributesSource: string, body: string): WorkflowSco
     label: attributes.label,
     domain: attributes.domain as WorkflowScope["domain"],
     metadata: parseWorkflowScopeMetadata(body),
+    ...(scopeMetadataPersistence !== undefined ? { metadataPersistence: scopeMetadataPersistence } : {}),
   };
 }
 
@@ -606,7 +735,8 @@ function parseWorkflowScopeMetadata(body: string): WorkflowScope["metadata"] | u
   if (!metadataMatch) {
     return undefined;
   }
-  const fields = [...(metadataMatch[1] ?? "").matchAll(/<bw:field\b([^>]*)>([\s\S]*?)<\/bw:field>/gu)]
+  // Match both self-closing (<bw:field .../>) and body-bearing (<bw:field ...>body</bw:field>)
+  const fields = [...(metadataMatch[1] ?? "").matchAll(/<bw:field\b([^>]*)(?:\/>|>([\s\S]*?)<\/bw:field>)/gu)]
     .map((match) => parseWorkflowScopeMetadataField(match[1] ?? "", match[2] ?? ""))
     .filter((field): field is NonNullable<WorkflowScope["metadata"]>[number] => field !== null);
   return fields.length > 0 ? fields : undefined;
@@ -621,10 +751,19 @@ function parseWorkflowScopeMetadataField(
     return null;
   }
   const valueType = attributes.type as NonNullable<WorkflowScope["metadata"]>[number]["valueType"] | undefined;
+  const fieldMetadataPersistence = parseClosedEnum(
+    attributes.metadataPersistence,
+    ["internal", "external", "inherit"] as const,
+  );
+  const fieldStorageRef = attributes.storageRef;
+  const fieldMetadataVersion = parseNonNegativeInt(attributes.metadataVersion);
   return {
     key: attributes.key,
     ...(valueType ? { valueType } : {}),
     value: parseWorkflowScopeMetadataValue(valueType, body),
+    ...(fieldMetadataPersistence !== undefined ? { metadataPersistence: fieldMetadataPersistence } : {}),
+    ...(fieldStorageRef !== undefined ? { storageRef: fieldStorageRef } : {}),
+    ...(fieldMetadataVersion !== undefined ? { metadataVersion: fieldMetadataVersion } : {}),
   };
 }