@form-engine-ts/core 5.0.0 → 5.1.0

package/dist/index.cjs

@@ -22,6 +22,9 @@ var index_exports = {};
 __export(index_exports, {
   DEFAULT_FIELD_TYPE_DEFINITIONS: () => DEFAULT_FIELD_TYPE_DEFINITIONS,
   EN_MESSAGES: () => EN_MESSAGES,
+  FormSubmissionError: () => FormSubmissionError,
+  FormSubmissionMetadataSchema: () => FormSubmissionMetadataSchema,
+  FormSubmissionWireSchema: () => FormSubmissionWireSchema,
   JA_MESSAGES: () => JA_MESSAGES,
   aggregateResponses: () => aggregateResponses,
   applyTransitionPlan: () => applyTransitionPlan,
@@ -77,6 +80,7 @@ __export(index_exports, {
   resolveLocalizedSchema: () => resolveLocalizedSchema,
   sanitizeSchema: () => sanitizeSchema,
   selectVisibleAnswers: () => selectVisibleAnswers,
+  toFormSubmissionWire: () => toFormSubmissionWire,
   transformFieldType: () => transformFieldType,
   validateAnswers: () => validateAnswers,
   validateFormSchema: () => validateFormSchema,
@@ -1686,15 +1690,28 @@ function serializeUnknown(value) {
   if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
   return JSON.stringify(value);
 }
+function submissionWithMetadata(submission) {
+  return { ...submission, metadata: submission.metadata ?? {} };
+}
 async function* exportResponsesToCsvStream(schema, submissions, options = {}) {
   assertValidFormSchema(schema);
   const includeDefaultColumns = options.includeDefaultColumns ?? true;
   const customColumns = options.columns ?? [];
+  const contractColumns = options.customColumns ?? [];
+  const includeLocale = options.includeLocale ?? true;
+  const includePiiStatus = options.includePiiStatus ?? false;
   const headers = [
-    ...includeDefaultColumns ? ["submissionId", "submittedAt", "locale", ...schema.fields.map((field) => field.id)] : [],
-    ...customColumns.map((column) => column.header)
+    ...includeDefaultColumns ? [
+      "submissionId",
+      "submittedAt",
+      ...includeLocale ? ["locale"] : [],
+      ...includePiiStatus ? ["piiStatus"] : [],
+      ...schema.fields.map((field) => field.id)
+    ] : [],
+    ...customColumns.map((column) => column.header),
+    ...contractColumns.map((column) => column.header)
   ];
-  const neutralizeFormulas = options.neutralizeFormulas ?? true;
+  const neutralizeFormulas = options.preventFormulaInjection ?? options.neutralizeFormulas ?? true;
   const header = headers.map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",");
   yield `${options.withBom ?? true ? "\uFEFF" : ""}${header}`;
   for await (const submission of submissions) {
@@ -1703,10 +1720,12 @@ async function* exportResponsesToCsvStream(schema, submissions, options = {}) {
     const response = asFormResponse(submission);
     const answers = response.answers;
     const visible = selectVisibleAnswers(schema, answers);
+    const piiStatus = response.metadata?.piiConfirmed === true ? "confirmed" : "unconfirmed";
     const defaultCells = includeDefaultColumns ? [
       response.responseId,
       response.submittedAt,
-      response.sourceLocale ?? "",
+      ...includeLocale ? [response.sourceLocale ?? ""] : [],
+      ...includePiiStatus ? [piiStatus] : [],
       ...schema.fields.map((field) => serializeUnknown(visible[field.id]))
     ] : [];
     const context = {
@@ -1716,8 +1735,9 @@ async function* exportResponsesToCsvStream(schema, submissions, options = {}) {
       schema
     };
     const customCells = await Promise.all(customColumns.map((column) => column.getValue(context)));
+    const contractCells = "values" in submission ? contractColumns.map((column) => column.getValue(submissionWithMetadata(submission), schema)) : contractColumns.map(() => void 0);
     yield `\r
-${[...defaultCells, ...customCells].map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",")}`;
+${[...defaultCells, ...customCells, ...contractCells].map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",")}`;
   }
 }
 function isWebWritableStream(writable) {
@@ -1774,23 +1794,51 @@ function exportResponsesToCsv(schema, responses, options = {}) {
       throw new TypeError(`Submission ${response.id} does not match ${schema.id}@${schema.version}.`);
     }
   }
+  const includeLocale = options.includeLocale ?? true;
+  const includePiiStatus = options.includePiiStatus ?? false;
+  const customColumns = options.customColumns ?? [];
+  const headers = [
+    "submissionId",
+    "submittedAt",
+    ...includeLocale ? ["locale"] : [],
+    ...includePiiStatus ? ["piiStatus"] : [],
+    ...schema.fields.map((field) => field.id),
+    ...customColumns.map((column) => column.header)
+  ];
   const rows = [
-    ["submissionId", "submittedAt", "locale", ...schema.fields.map((field) => field.id)],
+    headers,
     ...responses.map((response) => {
       const visible = selectVisibleAnswers(schema, response.values);
+      const piiStatus = response.metadata?.piiConfirmed === true ? "confirmed" : "unconfirmed";
+      const submissionForCustomColumns = submissionWithMetadata(response);
       return [
         response.id,
         response.submittedAt,
-        response.locale,
-        ...schema.fields.map((field) => serializeValue(visible[field.id]))
+        ...includeLocale ? [response.locale] : [],
+        ...includePiiStatus ? [piiStatus] : [],
+        ...schema.fields.map((field) => serializeValue(visible[field.id])),
+        ...customColumns.map((column) => column.getValue(submissionForCustomColumns, schema))
       ];
     })
   ];
-  const neutralizeFormulas = options.neutralizeFormulas ?? true;
+  const neutralizeFormulas = options.preventFormulaInjection ?? options.neutralizeFormulas ?? true;
   const csv = rows.map((row) => row.map((cell) => escapeCsvCell(cell, neutralizeFormulas)).join(",")).join("\r\n");
-  return options.withBom ?? true ? `\uFEFF${csv}` : csv;
+  return options.useBom ?? options.withBom ?? true ? `\uFEFF${csv}` : csv;
 }
 
+// src/errors.ts
+var FormSubmissionError = class extends Error {
+  payload;
+  constructor(payload) {
+    super(payload.messageKey);
+    this.name = "FormSubmissionError";
+    this.payload = payload;
+  }
+  toJSON() {
+    return this.payload;
+  }
+};
+
 // src/events.ts
 function bytesToHex(bytes) {
   return [...new Uint8Array(bytes)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
@@ -2113,7 +2161,20 @@ var EN_MESSAGES = Object.freeze({
   "workspace.errors.maxLocalesExceeded": "The maximum number of locales ({{max}}) has been reached.",
   "workspace.errors.readOnly": "This workspace is read-only.",
   "workspace.errors.adapterNotConfigured": "A translation adapter is not configured.",
-  "workspace.errors.translationFailed": "Translation failed."
+  "workspace.errors.translationFailed": "Translation failed.",
+  "workspace.header.title": "Translation workspace",
+  "workspace.header.sourceLocale": "Source language",
+  "workspace.header.targetLocale": "Target language",
+  "workspace.header.translateAll": "Translate all",
+  "workspace.header.progress": "{{translated}}/{{total}} translated ({{percent}}%)",
+  "workspace.slot.sourceText": "Source",
+  "workspace.slot.translatedText": "Translation",
+  "workspace.slot.translateSingle": "Translate this slot",
+  "workspace.slot.revertManual": "Revert manual translation",
+  "workspace.confirm.removeLocaleTitle": "Remove language?",
+  "workspace.confirm.removeLocaleMessage": "This will remove {{locale}} and its translations.",
+  "workspace.empty.noTargetLocales": "No target languages are configured.",
+  "workspace.empty.noSlotsToTranslate": "There are no translation slots for this language."
 });
 
 // src/i18n/catalogs/ja.ts
@@ -2285,7 +2346,20 @@ var JA_MESSAGES = Object.freeze({
   "workspace.errors.maxLocalesExceeded": "\u767B\u9332\u53EF\u80FD\u306A\u6700\u5927\u8A00\u8A9E\u6570 ({{max}}) \u306B\u9054\u3057\u307E\u3057\u305F\u3002",
   "workspace.errors.readOnly": "\u8AAD\u307F\u53D6\u308A\u5C02\u7528\u30E2\u30FC\u30C9\u306E\u305F\u3081\u5909\u66F4\u3067\u304D\u307E\u305B\u3093\u3002",
   "workspace.errors.adapterNotConfigured": "\u7FFB\u8A33\u30A2\u30C0\u30D7\u30BF\u30FC\u304C\u8A2D\u5B9A\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002",
-  "workspace.errors.translationFailed": "\u7FFB\u8A33\u51E6\u7406\u306B\u5931\u6557\u3057\u307E\u3057\u305F\u3002"
+  "workspace.errors.translationFailed": "\u7FFB\u8A33\u51E6\u7406\u306B\u5931\u6557\u3057\u307E\u3057\u305F\u3002",
+  "workspace.header.title": "\u591A\u8A00\u8A9E\u7FFB\u8A33\u30EF\u30FC\u30AF\u30B9\u30DA\u30FC\u30B9",
+  "workspace.header.sourceLocale": "\u5143\u8A00\u8A9E",
+  "workspace.header.targetLocale": "\u7FFB\u8A33\u8A00\u8A9E",
+  "workspace.header.translateAll": "\u4E00\u62EC\u81EA\u52D5\u7FFB\u8A33",
+  "workspace.header.progress": "{{translated}}/{{total}} \u7FFB\u8A33\u6E08\u307F ({{percent}}%)",
+  "workspace.slot.sourceText": "\u539F\u6587",
+  "workspace.slot.translatedText": "\u7FFB\u8A33\u6587",
+  "workspace.slot.translateSingle": "\u3053\u306E\u9805\u76EE\u3092\u7FFB\u8A33",
+  "workspace.slot.revertManual": "\u624B\u52D5\u7FFB\u8A33\u3092\u5143\u306B\u623B\u3059",
+  "workspace.confirm.removeLocaleTitle": "\u8A00\u8A9E\u3092\u524A\u9664\u3057\u307E\u3059\u304B\uFF1F",
+  "workspace.confirm.removeLocaleMessage": "{{locale}} \u3068\u305D\u306E\u7FFB\u8A33\u3092\u524A\u9664\u3057\u307E\u3059\u3002",
+  "workspace.empty.noTargetLocales": "\u7FFB\u8A33\u5148\u306E\u8A00\u8A9E\u304C\u8A2D\u5B9A\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002",
+  "workspace.empty.noSlotsToTranslate": "\u3053\u306E\u8A00\u8A9E\u306B\u306F\u7FFB\u8A33\u9805\u76EE\u304C\u3042\u308A\u307E\u305B\u3093\u3002"
 });
 
 // src/i18n/translator.ts
@@ -2574,6 +2648,19 @@ function matchesSubmissionPageFilters(submission, options) {
   );
 }
 
+// src/schemas/submission.zod.ts
+var import_zod = require("zod");
+var FormSubmissionMetadataSchema = import_zod.z.record(import_zod.z.string(), import_zod.z.unknown());
+var FormSubmissionWireSchema = import_zod.z.object({
+  id: import_zod.z.string().min(1),
+  formId: import_zod.z.string().min(1),
+  formVersion: import_zod.z.number().int().positive(),
+  values: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()),
+  metadata: FormSubmissionMetadataSchema,
+  submittedAt: import_zod.z.string().datetime(),
+  schemaRevision: import_zod.z.number().int().optional()
+});
+
 // src/validation.ts
 var DEFAULT_MESSAGES = {
   required: "validation.required",
@@ -2754,6 +2841,19 @@ function toFormValues(answers) {
 function isFormValue(value) {
   return value === void 0 || typeof value === "string" || typeof value === "number" || typeof value === "boolean" || Array.isArray(value) && value.every((item) => typeof item === "string");
 }
+function toFormSubmissionWire(submission) {
+  const { id, formId, formVersion, values, answers, metadata, submittedAt, schemaRevision } = submission;
+  const targetValues = values ?? answers ?? {};
+  return {
+    id,
+    formId,
+    formVersion,
+    values: { ...targetValues },
+    metadata: { ...metadata ?? {} },
+    submittedAt,
+    ...schemaRevision === void 0 ? {} : { schemaRevision }
+  };
+}
 function createSubmission(schemaOrInput, values, options) {
   if ("answers" in schemaOrInput) {
     const input = schemaOrInput;
@@ -3177,18 +3277,20 @@ var migrateSchemaTranslationMetadata = (schema, migratorOrOptions) => {
   };
 };
 var removeLocaleFromSchema = (schema, localeToRemove) => {
-  if (localeToRemove === schema.defaultLocale) {
+  const normalizedLocaleToRemove = normalizeLocale(localeToRemove) ?? localeToRemove;
+  const normalizedDefaultLocale = schema.defaultLocale === void 0 ? void 0 : normalizeLocale(schema.defaultLocale) ?? schema.defaultLocale;
+  if (normalizedLocaleToRemove === normalizedDefaultLocale) {
     throw new Error(`Cannot remove defaultLocale: ${localeToRemove}`);
   }
-  const form = removeLocalizedNodeLocale(schema, localeToRemove);
+  const form = removeLocalizedNodeLocale(schema, normalizedLocaleToRemove);
   const fields = schema.fields.map((field) => {
-    const localizedField = removeLocalizedNodeLocale(field, localeToRemove);
+    const localizedField = removeLocalizedNodeLocale(field, normalizedLocaleToRemove);
     if (!("options" in localizedField)) return localizedField;
     return {
       ...localizedField,
       options: localizedField.options.map((option) => {
-        const translations = removeLocaleRecord(option.translations, localeToRemove);
-        const translationMetadata = removeLocaleRecord(option.translationMetadata, localeToRemove);
+        const translations = removeLocaleRecord(option.translations, normalizedLocaleToRemove);
+        const translationMetadata = removeLocaleRecord(option.translationMetadata, normalizedLocaleToRemove);
         const { translations: _translations, translationMetadata: _translationMetadata, ...base } = option;
         return {
           ...base,
@@ -3198,10 +3300,12 @@ var removeLocaleFromSchema = (schema, localeToRemove) => {
       })
     };
   });
-  const pages = schema.pages?.map((page) => removeLocalizedNodeLocale(page, localeToRemove));
+  const pages = schema.pages?.map((page) => removeLocalizedNodeLocale(page, normalizedLocaleToRemove));
   return {
     ...form,
-    supportedLocales: (schema.supportedLocales ?? []).filter((locale) => locale !== localeToRemove),
+    supportedLocales: (schema.supportedLocales ?? []).filter(
+      (locale) => (normalizeLocale(locale) ?? locale) !== normalizedLocaleToRemove
+    ),
     fields,
     ...pages === void 0 ? {} : { pages }
   };
@@ -3660,6 +3764,9 @@ async function commitVersionTransition(options) {
 0 && (module.exports = {
   DEFAULT_FIELD_TYPE_DEFINITIONS,
   EN_MESSAGES,
+  FormSubmissionError,
+  FormSubmissionMetadataSchema,
+  FormSubmissionWireSchema,
   JA_MESSAGES,
   aggregateResponses,
   applyTransitionPlan,
@@ -3715,6 +3822,7 @@ async function commitVersionTransition(options) {
   resolveLocalizedSchema,
   sanitizeSchema,
   selectVisibleAnswers,
+  toFormSubmissionWire,
   transformFieldType,
   validateAnswers,
   validateFormSchema,

package/dist/index.d.cts

@@ -1,8 +1,22 @@
+import { z } from 'zod';
+
+type AggregationSkipReason = "missing_field" | "type_mismatch" | "invalid_option" | "unsupported_version" | "locale_mismatch" | "pii_unconfirmed";
+interface AggregationReport {
+    readonly totalProcessed: number;
+    readonly aggregatedCount: number;
+    readonly skippedItems: readonly {
+        readonly submissionId: string;
+        readonly fieldId: string;
+        readonly reason: AggregationSkipReason;
+    }[];
+}
+
 type KnownBuilderTranslationKey = "builder.formTitle" | "builder.formDescription" | "builder.completionMessage" | "builder.addQuestion" | "builder.actions.addField" | "builder.actions.deleteField" | "builder.actions.moveUp" | "builder.actions.moveDown" | "builder.actions.add" | "builder.actions.delete" | "builder.actions.edit" | "builder.actions.settings" | "builder.actions.translate" | "builder.actions.close" | "builder.actions.dragHandle" | "builder.fields.selectType" | "builder.fields.typeText" | "builder.fields.typeTextarea" | "builder.fields.typeNumber" | "builder.fields.typeRadio" | "builder.fields.typeCheckbox" | "builder.fields.typeSelect" | "builder.fields.typeRating" | "builder.fields.typeMultiSelect" | "builder.fieldType.text" | "builder.fieldType.textarea" | "builder.fieldType.number" | "builder.fieldType.radio" | "builder.fieldType.checkbox" | "builder.fieldType.select" | "builder.fieldType.rating" | "builder.fieldType.multi-select" | "builder.fieldTypeDescription.text" | "builder.fieldTypeDescription.textarea" | "builder.fieldTypeDescription.number" | "builder.fieldTypeDescription.radio" | "builder.fieldTypeDescription.checkbox" | "builder.fieldTypeDescription.select" | "builder.fieldTypeDescription.rating" | "builder.fieldTypeDescription.multi-select" | "builder.fieldCategory.text" | "builder.fieldCategory.choice" | "builder.fieldCategory.number" | "builder.fieldCategory.advanced" | "builder.required" | "builder.options" | "builder.localization.title" | "builder.localization" | "builder.localization.addLocale" | "builder.localization.selectLocaleToAdd" | "builder.localization.defaultLocale" | "builder.localization.translateAll" | "builder.localization.noLocalesConfigured" | "builder.localization.localesConfiguredSummary" | "builder.localization.allLocalesAdded" | "builder.localization.maxLocalesReached" | "builder.submissionSettings.title" | "builder.submissionSettings.showConfirmation" | "builder.submissionSettings.renderMode" | "builder.formBuilder" | "builder.basicSettings" | "builder.description" | "builder.moveUp" | "builder.moveDown" | "builder.delete" | "builder.deleteAction" | "builder.questionTitle" | "builder.questionTitlePlaceholder" | "builder.newQuestionTitle" | "builder.type" | "builder.minimum" | "builder.maximum" | "builder.minimumLength" | "builder.maximumLength" | "builder.pattern" | "builder.step" | "builder.optionLabel" | "builder.optionLabelPlaceholder" | "builder.newOptionLabel" | "builder.remove" | "builder.addOption" | "builder.displayCondition" | "builder.alwaysVisible" | "builder.conditionOperator" | "builder.conditionValue" | "builder.conditionTrue" | "builder.conditionFalse" | "builder.pages" | "builder.enablePages" | "builder.addPage" | "builder.newPage" | "builder.pageTitle" | "builder.pageDescription" | "builder.pageQuestion" | "builder.questionPage" | "builder.pageCondition" | "builder.unassigned" | "builder.defaultLocale" | "builder.supportedLocales" | "builder.addLocale" | "builder.editLocale" | "builder.autoTranslate" | "builder.translating" | "builder.translationLocale" | "builder.selectLocale" | "builder.selectLocaleToAdd" | "builder.translation" | "builder.translatedFormTitle" | "builder.translatedFormDescription" | "builder.translatedCompletionMessage" | "builder.translatedQuestionTitle" | "builder.translatedDescription" | "builder.translationUnavailable" | "builder.operator.equals" | "builder.operator.not_equals" | "builder.operator.contains" | "builder.operator.not_empty" | "builder.showConfirmationBeforeSubmit" | "builder.confirmationRenderMode";
 type BuilderTranslationKey = KnownBuilderTranslationKey;
 type RendererTranslationKey = "renderer.submitButton" | "renderer.submittingButton" | "renderer.retryButton" | "renderer.requiredField" | "renderer.alreadySubmittedTitle" | "renderer.alreadySubmittedMessage" | "renderer.serverErrorSummary" | "renderer.confirmSensitiveDataTitle" | "renderer.confirmSensitiveDataMessage" | "renderer.confirmButton" | "renderer.cancelButton" | "form.submit" | "form.submitting" | "form.back" | "form.next" | "form.step" | "form.draftRestored" | "form.submissionBlocked" | "form.confirmSensitiveData" | "form.confirmSubmission" | "form.cancelSubmission" | "form.yes" | "form.no" | "form.alreadySubmitted" | "form.submitAnother" | "validation.required" | "validation.invalidOption" | "validation.invalidType" | "validation.max" | "validation.maxLength" | "validation.maxSelections" | "validation.min" | "validation.minLength" | "validation.minSelections" | "validation.pattern" | "validation.sensitiveData" | "validation.step" | "validation.unknownField";
 type TranslationWorkspaceTranslationKey = "workspace.title" | "workspace.status.missing" | "workspace.status.translated" | "workspace.status.stale" | "workspace.status.manual" | "workspace.status.manualStale" | "workspace.errors.localeNotAllowed" | "workspace.errors.maxLocalesExceeded" | "workspace.errors.readOnly" | "workspace.errors.adapterNotConfigured" | "workspace.errors.translationFailed";
-type FormEngineTranslationKey = KnownBuilderTranslationKey | RendererTranslationKey | TranslationWorkspaceTranslationKey;
+type TranslationWorkspaceDetailedKey = "workspace.header.title" | "workspace.header.sourceLocale" | "workspace.header.targetLocale" | "workspace.header.translateAll" | "workspace.header.progress" | "workspace.slot.sourceText" | "workspace.slot.translatedText" | "workspace.slot.translateSingle" | "workspace.slot.revertManual" | "workspace.confirm.removeLocaleTitle" | "workspace.confirm.removeLocaleMessage" | "workspace.empty.noTargetLocales" | "workspace.empty.noSlotsToTranslate";
+type FormEngineTranslationKey = KnownBuilderTranslationKey | RendererTranslationKey | TranslationWorkspaceTranslationKey | TranslationWorkspaceDetailedKey;
 type FormEngineMessages = Partial<Record<FormEngineTranslationKey, string>>;
 
 type Result<T, E> = {
@@ -199,6 +213,18 @@ type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
 interface BaseSubmissionMetadata {
     readonly [key: string]: JsonValue | undefined;
 }
+/** A contract or tenant-managed locale and its translation capabilities. */
+interface LocaleOption {
+    /** Canonical BCP 47 locale tag. */
+    readonly locale: string;
+    /** Human-readable locale name. */
+    readonly label: string;
+    /** Whether automatic translation is allowed for this locale. Defaults to true. */
+    readonly translatable?: boolean;
+    /** Whether the locale may be removed from the form. Defaults to true. */
+    readonly removable?: boolean;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
 /** Arbitrary, JSON-serializable data preserved by every form-engine operation. */
 interface ExtensibleNode {
     readonly metadata?: Readonly<Record<string, JsonValue>>;
@@ -360,6 +386,16 @@ type FormSubmission<TMeta extends BaseSubmissionMetadata | undefined = undefined
 } : {
     readonly metadata: TMeta;
 });
+/** Clean network and persistence representation of a form submission. */
+interface FormSubmissionWire<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata> {
+    readonly id: string;
+    readonly formId: string;
+    readonly formVersion: number;
+    readonly values: Record<string, unknown>;
+    readonly metadata: TMeta;
+    readonly submittedAt: string;
+    readonly schemaRevision?: number;
+}
 interface CreateSubmissionInput<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata> {
     readonly id?: string;
     readonly formId: string;
@@ -600,9 +636,21 @@ interface ResponseAccumulatorOptions {
 }
 declare function createResponseAccumulator(schema: FormSchema, options?: ResponseAccumulatorOptions): ResponseAccumulator;
 declare function escapeCsvCell(value: string | number | boolean | null | undefined, neutralizeFormulas?: boolean): string;
-interface CsvExportOptions {
+interface CsvColumnDefinition<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata> {
+    readonly key: string;
+    readonly header: string;
+    readonly getValue: (submission: FormSubmission<TMeta>, schema: FormSchema) => string | number | boolean | null | undefined;
+}
+interface CsvExportOptions<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata> {
     readonly withBom?: boolean;
     readonly neutralizeFormulas?: boolean;
+    /** Alias for withBom used by the public export contract. */
+    readonly useBom?: boolean;
+    /** Alias for neutralizeFormulas used by the public export contract. */
+    readonly preventFormulaInjection?: boolean;
+    readonly customColumns?: readonly CsvColumnDefinition<TMeta>[];
+    readonly includePiiStatus?: boolean;
+    readonly includeLocale?: boolean;
 }
 interface CsvColumnDef {
     readonly header: string;
@@ -629,6 +677,45 @@ interface NodeWritableStream {
 declare function pipeResponsesToCsvStream(schema: FormSchema, submissions: AsyncIterable<AccumulatorResponse>, writable: WritableStream<Uint8Array> | NodeWritableStream, options?: StreamCsvOptions): Promise<void>;
 declare function exportResponsesToCsv(schema: FormSchema, responses: readonly FormSubmission[], options?: CsvExportOptions): string;
 
+interface SensitiveDataFinding {
+    readonly fieldId: string;
+    readonly type: string;
+    readonly start?: number;
+    readonly end?: number;
+    readonly matchedText?: string;
+    readonly maskedText?: string;
+}
+interface PrivacyEngine {
+    detect(schema: FormSchema, values: Record<string, unknown>): readonly SensitiveDataFinding[];
+}
+interface SubmissionValidationResult {
+    readonly valid: boolean;
+    readonly fieldErrors: Readonly<Record<string, string>>;
+    readonly formErrors: readonly string[];
+    readonly piiFindings?: readonly SensitiveDataFinding[];
+}
+declare function validateAnswers(schema: FormSchema, values: FormValues): AnswerValidationResult;
+declare function validatePageAnswers(schema: FormSchema, pageIndex: number, values: FormValues): AnswerValidationResult;
+declare function validateSubmission<TMeta extends BaseSubmissionMetadata | undefined = undefined>(schema: FormSchema, submission: FormSubmission<TMeta>, options?: {
+    readonly privacyEngine?: PrivacyEngine;
+}): SubmissionValidationResult;
+
+interface FormSubmissionSerializedError {
+    readonly code: "VALIDATION_FAILED" | "PII_CONFIRMATION_REQUIRED" | "SUBMISSION_BLOCKED" | "STORAGE_ERROR";
+    readonly messageKey: FormEngineTranslationKey | string;
+    readonly messageParams?: Readonly<Record<string, unknown>>;
+    readonly fieldErrors: Readonly<Record<string, string>>;
+    readonly formErrors: readonly string[];
+    readonly piiFindings?: readonly SensitiveDataFinding[];
+    readonly piiWarningAcknowledged?: boolean;
+}
+/** Error with a stable, JSON-serializable payload for RPC boundaries. */
+declare class FormSubmissionError extends Error {
+    readonly payload: FormSubmissionSerializedError;
+    constructor(payload: FormSubmissionSerializedError);
+    toJSON(): FormSubmissionSerializedError;
+}
+
 type FormEventType = "response.submitted" | "schema.updated";
 interface FormEvent<T = unknown> {
     readonly id: string;
@@ -772,12 +859,28 @@ interface ValidateFormSchemaOptions {
 declare function validateFormSchema(input: unknown, options?: ValidateFormSchemaOptions): SchemaValidationResult;
 declare function assertValidFormSchema(input: unknown): asserts input is FormSchema;
 
+/** Runtime schema for the JSON metadata carried by a submission wire payload. */
+declare const FormSubmissionMetadataSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+/** Runtime schema for the clean, alias-free submission wire format. */
+declare const FormSubmissionWireSchema: z.ZodObject<{
+    id: z.ZodString;
+    formId: z.ZodString;
+    formVersion: z.ZodNumber;
+    values: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    submittedAt: z.ZodString;
+    schemaRevision: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type FormSubmissionWireSchemaType = z.infer<typeof FormSubmissionWireSchema>;
+
 interface CreateSubmissionOptions<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata> extends ExtensibleNode {
     readonly id: string;
     readonly locale: string;
     readonly submittedAt: string;
     readonly metadata?: TMeta & Readonly<Record<string, JsonValue>>;
 }
+declare function toFormSubmissionWire<TMeta extends BaseSubmissionMetadata>(submission: FormSubmission<TMeta>): FormSubmissionWire<TMeta>;
+declare function toFormSubmissionWire(submission: FormSubmission): FormSubmissionWire;
 declare function createSubmission(schema: FormSchema, values: FormValues, options: CreateSubmissionOptions): FormSubmission;
 declare function createSubmission<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata>(schema: FormSchema, values: FormValues, options: CreateSubmissionOptions<TMeta>): FormSubmission<TMeta>;
 declare function createSubmission<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata>(input: CreateSubmissionInput<TMeta>): FormSubmission<TMeta>;
@@ -897,29 +1000,6 @@ declare function populateSchemaTranslations(schema: FormSchema, targetLocales: r
 }>;
 declare function resolveFormTranslation(schema: FormSchema, adapter: AsyncTranslationAdapter, targetLocale: string, sourceLocale?: string): Promise<FormSchema>;
 
-interface SensitiveDataFinding {
-    readonly fieldId: string;
-    readonly type: string;
-    readonly start?: number;
-    readonly end?: number;
-    readonly matchedText?: string;
-    readonly maskedText?: string;
-}
-interface PrivacyEngine {
-    detect(schema: FormSchema, values: Record<string, unknown>): readonly SensitiveDataFinding[];
-}
-interface SubmissionValidationResult {
-    readonly valid: boolean;
-    readonly fieldErrors: Readonly<Record<string, string>>;
-    readonly formErrors: readonly string[];
-    readonly piiFindings?: readonly SensitiveDataFinding[];
-}
-declare function validateAnswers(schema: FormSchema, values: FormValues): AnswerValidationResult;
-declare function validatePageAnswers(schema: FormSchema, pageIndex: number, values: FormValues): AnswerValidationResult;
-declare function validateSubmission<TMeta extends BaseSubmissionMetadata | undefined = undefined>(schema: FormSchema, submission: FormSubmission<TMeta>, options?: {
-    readonly privacyEngine?: PrivacyEngine;
-}): SubmissionValidationResult;
-
 declare function isDisplayConditionGroupSatisfied(group: DisplayConditionGroup, currentAnswers: Readonly<Record<string, unknown>>): boolean;
 declare function isQuestionVisible(question: FormField, currentAnswers: Readonly<Record<string, unknown>>): boolean;
 declare function isDisplayConditionSatisfied(condition: DisplayCondition | undefined, currentAnswers: Readonly<Record<string, unknown>>): boolean;
@@ -927,4 +1007,4 @@ declare function calculatePageVisibility(schema: FormSchema, currentAnswers: Rea
 declare function calculateFieldVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function selectVisibleAnswers(schema: FormSchema, currentAnswers: FormValues): FormValues;
 
-export { type AccumulatorReport, type AccumulatorResponse, type AccumulatorSkipReason, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type BaseFieldConstraintRule, type BaseSubmissionMetadata, type BuilderTranslationKey, type CanonicalTranslationMetadata, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceFieldConstraintRule, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type CommitVersionTransitionOptions, type ConditionOperator, type ConditionValue, type CreateSubmissionInput, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnContext, type CsvColumnDef, type CsvExportOptions, type CursorPagingOptions, DEFAULT_FIELD_TYPE_DEFINITIONS, type DeleteDraftOptions, type DisplayCondition, type DisplayConditionGroup, type DisplayRule, EN_MESSAGES, type ExtensibleNode, type FieldConstraintRule, type FieldDisplayCondition, type FieldOption, type FieldType, type FieldTypeDefinition, type FormAnalytics, type FormEngineMessages, type FormEngineTranslationKey, type FormEngineTranslator, type FormEngineTranslatorOptions, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormSubmissionSettings, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type FormVersionTransitionPlan, JA_MESSAGES, type JsonValue, type KnownBuilderTranslationKey, type LegacyTranslationMetadata, type LocalizedText, type MigrateSchemaTranslationMetadataOptions, type MultiSelectField, type NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PaginatedResult, type PaginationIteratorOptions, type PopulateTranslationOptions, type PopulateTranslationsOptions, type PrivacyEngine, type PublishDraftOptions, type PublishDraftResult, type Question, type QuestionAggregate, type QuestionType, type RatingField, type RatingFieldConstraintRule, type RendererTranslationKey, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SanitizeSchemaOptions, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type SensitiveDataFinding, type StorageAdapter, type StorageCommitError, type StorageCursor, type StorageFilterCriteria, type StreamCsvOptions, type SubmissionCursorPayload, type SubmissionCursorValue, type SubmissionFilter, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type SubmissionValidationResult, type TextAnswerCursorPayload, type TextAnswerCursorValue, type TextAnswerItem, type TextAnswerPage, type TextAnswerPageQueryOptions, type TextField, type TextFieldConstraintRule, type TextQuestionAggregate, type TranslationAdapter, type TranslationMetadataMigrator, type TranslationMigrationContext, type TranslationProviderError, type TranslationReport, type TranslationSlot, type TranslationStatus, type TranslationWorkspaceTranslationKey, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionContext, type VersionTransitionError, type VersionTransitionEvent, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, applyTransitionPlan, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, collectTranslationSlots, commitVersionTransition, computeSourceTextHash, createCloneTransitionPlan, createDeleteDraftTransitionPlan, createFormEngineTranslator, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeStorageSubmissionCursor, decodeStorageTextAnswerCursor, decodeSubmissionCursor, decodeTextAnswerCursor, deleteDraft, dispatchWebhook, encodeStorageSubmissionCursor, encodeStorageTextAnswerCursor, encodeSubmissionCursor, encodeTextAnswerCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, getTranslationStatus, isDisplayConditionGroupSatisfied, isDisplayConditionSatisfied, isManualTranslationMetadata, isQuestionVisible, iterateSubmissionPages, jsonValuesEqual, matchesSubmissionFilter, matchesSubmissionPageFilters, migrateSchemaTranslationMetadata, normalizeLocale, normalizeSubmissionPageSize, paginateWithFilter, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, removeLocaleFromSchema, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure, validateSubmission };
+export { type AccumulatorReport, type AccumulatorResponse, type AccumulatorSkipReason, type AggregationReport, type AggregationSkipReason, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type BaseFieldConstraintRule, type BaseSubmissionMetadata, type BuilderTranslationKey, type CanonicalTranslationMetadata, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceFieldConstraintRule, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type CommitVersionTransitionOptions, type ConditionOperator, type ConditionValue, type CreateSubmissionInput, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnContext, type CsvColumnDef, type CsvColumnDefinition, type CsvExportOptions, type CursorPagingOptions, DEFAULT_FIELD_TYPE_DEFINITIONS, type DeleteDraftOptions, type DisplayCondition, type DisplayConditionGroup, type DisplayRule, EN_MESSAGES, type ExtensibleNode, type FieldConstraintRule, type FieldDisplayCondition, type FieldOption, type FieldType, type FieldTypeDefinition, type FormAnalytics, type FormEngineMessages, type FormEngineTranslationKey, type FormEngineTranslator, type FormEngineTranslatorOptions, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, FormSubmissionError, FormSubmissionMetadataSchema, type FormSubmissionSerializedError, type FormSubmissionSettings, type FormSubmissionWire, FormSubmissionWireSchema, type FormSubmissionWireSchemaType, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type FormVersionTransitionPlan, JA_MESSAGES, type JsonValue, type KnownBuilderTranslationKey, type LegacyTranslationMetadata, type LocaleOption, type LocalizedText, type MigrateSchemaTranslationMetadataOptions, type MultiSelectField, type NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PaginatedResult, type PaginationIteratorOptions, type PopulateTranslationOptions, type PopulateTranslationsOptions, type PrivacyEngine, type PublishDraftOptions, type PublishDraftResult, type Question, type QuestionAggregate, type QuestionType, type RatingField, type RatingFieldConstraintRule, type RendererTranslationKey, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SanitizeSchemaOptions, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type SensitiveDataFinding, type StorageAdapter, type StorageCommitError, type StorageCursor, type StorageFilterCriteria, type StreamCsvOptions, type SubmissionCursorPayload, type SubmissionCursorValue, type SubmissionFilter, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type SubmissionValidationResult, type TextAnswerCursorPayload, type TextAnswerCursorValue, type TextAnswerItem, type TextAnswerPage, type TextAnswerPageQueryOptions, type TextField, type TextFieldConstraintRule, type TextQuestionAggregate, type TranslationAdapter, type TranslationMetadataMigrator, type TranslationMigrationContext, type TranslationProviderError, type TranslationReport, type TranslationSlot, type TranslationStatus, type TranslationWorkspaceDetailedKey, type TranslationWorkspaceTranslationKey, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionContext, type VersionTransitionError, type VersionTransitionEvent, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, applyTransitionPlan, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, collectTranslationSlots, commitVersionTransition, computeSourceTextHash, createCloneTransitionPlan, createDeleteDraftTransitionPlan, createFormEngineTranslator, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeStorageSubmissionCursor, decodeStorageTextAnswerCursor, decodeSubmissionCursor, decodeTextAnswerCursor, deleteDraft, dispatchWebhook, encodeStorageSubmissionCursor, encodeStorageTextAnswerCursor, encodeSubmissionCursor, encodeTextAnswerCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, getTranslationStatus, isDisplayConditionGroupSatisfied, isDisplayConditionSatisfied, isManualTranslationMetadata, isQuestionVisible, iterateSubmissionPages, jsonValuesEqual, matchesSubmissionFilter, matchesSubmissionPageFilters, migrateSchemaTranslationMetadata, normalizeLocale, normalizeSubmissionPageSize, paginateWithFilter, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, removeLocaleFromSchema, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, toFormSubmissionWire, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure, validateSubmission };

package/dist/index.d.ts

@@ -1,8 +1,22 @@
+import { z } from 'zod';
+
+type AggregationSkipReason = "missing_field" | "type_mismatch" | "invalid_option" | "unsupported_version" | "locale_mismatch" | "pii_unconfirmed";
+interface AggregationReport {
+    readonly totalProcessed: number;
+    readonly aggregatedCount: number;
+    readonly skippedItems: readonly {
+        readonly submissionId: string;
+        readonly fieldId: string;
+        readonly reason: AggregationSkipReason;
+    }[];
+}
+
 type KnownBuilderTranslationKey = "builder.formTitle" | "builder.formDescription" | "builder.completionMessage" | "builder.addQuestion" | "builder.actions.addField" | "builder.actions.deleteField" | "builder.actions.moveUp" | "builder.actions.moveDown" | "builder.actions.add" | "builder.actions.delete" | "builder.actions.edit" | "builder.actions.settings" | "builder.actions.translate" | "builder.actions.close" | "builder.actions.dragHandle" | "builder.fields.selectType" | "builder.fields.typeText" | "builder.fields.typeTextarea" | "builder.fields.typeNumber" | "builder.fields.typeRadio" | "builder.fields.typeCheckbox" | "builder.fields.typeSelect" | "builder.fields.typeRating" | "builder.fields.typeMultiSelect" | "builder.fieldType.text" | "builder.fieldType.textarea" | "builder.fieldType.number" | "builder.fieldType.radio" | "builder.fieldType.checkbox" | "builder.fieldType.select" | "builder.fieldType.rating" | "builder.fieldType.multi-select" | "builder.fieldTypeDescription.text" | "builder.fieldTypeDescription.textarea" | "builder.fieldTypeDescription.number" | "builder.fieldTypeDescription.radio" | "builder.fieldTypeDescription.checkbox" | "builder.fieldTypeDescription.select" | "builder.fieldTypeDescription.rating" | "builder.fieldTypeDescription.multi-select" | "builder.fieldCategory.text" | "builder.fieldCategory.choice" | "builder.fieldCategory.number" | "builder.fieldCategory.advanced" | "builder.required" | "builder.options" | "builder.localization.title" | "builder.localization" | "builder.localization.addLocale" | "builder.localization.selectLocaleToAdd" | "builder.localization.defaultLocale" | "builder.localization.translateAll" | "builder.localization.noLocalesConfigured" | "builder.localization.localesConfiguredSummary" | "builder.localization.allLocalesAdded" | "builder.localization.maxLocalesReached" | "builder.submissionSettings.title" | "builder.submissionSettings.showConfirmation" | "builder.submissionSettings.renderMode" | "builder.formBuilder" | "builder.basicSettings" | "builder.description" | "builder.moveUp" | "builder.moveDown" | "builder.delete" | "builder.deleteAction" | "builder.questionTitle" | "builder.questionTitlePlaceholder" | "builder.newQuestionTitle" | "builder.type" | "builder.minimum" | "builder.maximum" | "builder.minimumLength" | "builder.maximumLength" | "builder.pattern" | "builder.step" | "builder.optionLabel" | "builder.optionLabelPlaceholder" | "builder.newOptionLabel" | "builder.remove" | "builder.addOption" | "builder.displayCondition" | "builder.alwaysVisible" | "builder.conditionOperator" | "builder.conditionValue" | "builder.conditionTrue" | "builder.conditionFalse" | "builder.pages" | "builder.enablePages" | "builder.addPage" | "builder.newPage" | "builder.pageTitle" | "builder.pageDescription" | "builder.pageQuestion" | "builder.questionPage" | "builder.pageCondition" | "builder.unassigned" | "builder.defaultLocale" | "builder.supportedLocales" | "builder.addLocale" | "builder.editLocale" | "builder.autoTranslate" | "builder.translating" | "builder.translationLocale" | "builder.selectLocale" | "builder.selectLocaleToAdd" | "builder.translation" | "builder.translatedFormTitle" | "builder.translatedFormDescription" | "builder.translatedCompletionMessage" | "builder.translatedQuestionTitle" | "builder.translatedDescription" | "builder.translationUnavailable" | "builder.operator.equals" | "builder.operator.not_equals" | "builder.operator.contains" | "builder.operator.not_empty" | "builder.showConfirmationBeforeSubmit" | "builder.confirmationRenderMode";
 type BuilderTranslationKey = KnownBuilderTranslationKey;
 type RendererTranslationKey = "renderer.submitButton" | "renderer.submittingButton" | "renderer.retryButton" | "renderer.requiredField" | "renderer.alreadySubmittedTitle" | "renderer.alreadySubmittedMessage" | "renderer.serverErrorSummary" | "renderer.confirmSensitiveDataTitle" | "renderer.confirmSensitiveDataMessage" | "renderer.confirmButton" | "renderer.cancelButton" | "form.submit" | "form.submitting" | "form.back" | "form.next" | "form.step" | "form.draftRestored" | "form.submissionBlocked" | "form.confirmSensitiveData" | "form.confirmSubmission" | "form.cancelSubmission" | "form.yes" | "form.no" | "form.alreadySubmitted" | "form.submitAnother" | "validation.required" | "validation.invalidOption" | "validation.invalidType" | "validation.max" | "validation.maxLength" | "validation.maxSelections" | "validation.min" | "validation.minLength" | "validation.minSelections" | "validation.pattern" | "validation.sensitiveData" | "validation.step" | "validation.unknownField";
 type TranslationWorkspaceTranslationKey = "workspace.title" | "workspace.status.missing" | "workspace.status.translated" | "workspace.status.stale" | "workspace.status.manual" | "workspace.status.manualStale" | "workspace.errors.localeNotAllowed" | "workspace.errors.maxLocalesExceeded" | "workspace.errors.readOnly" | "workspace.errors.adapterNotConfigured" | "workspace.errors.translationFailed";
-type FormEngineTranslationKey = KnownBuilderTranslationKey | RendererTranslationKey | TranslationWorkspaceTranslationKey;
+type TranslationWorkspaceDetailedKey = "workspace.header.title" | "workspace.header.sourceLocale" | "workspace.header.targetLocale" | "workspace.header.translateAll" | "workspace.header.progress" | "workspace.slot.sourceText" | "workspace.slot.translatedText" | "workspace.slot.translateSingle" | "workspace.slot.revertManual" | "workspace.confirm.removeLocaleTitle" | "workspace.confirm.removeLocaleMessage" | "workspace.empty.noTargetLocales" | "workspace.empty.noSlotsToTranslate";
+type FormEngineTranslationKey = KnownBuilderTranslationKey | RendererTranslationKey | TranslationWorkspaceTranslationKey | TranslationWorkspaceDetailedKey;
 type FormEngineMessages = Partial<Record<FormEngineTranslationKey, string>>;
 
 type Result<T, E> = {
@@ -199,6 +213,18 @@ type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
 interface BaseSubmissionMetadata {
     readonly [key: string]: JsonValue | undefined;
 }
+/** A contract or tenant-managed locale and its translation capabilities. */
+interface LocaleOption {
+    /** Canonical BCP 47 locale tag. */
+    readonly locale: string;
+    /** Human-readable locale name. */
+    readonly label: string;
+    /** Whether automatic translation is allowed for this locale. Defaults to true. */
+    readonly translatable?: boolean;
+    /** Whether the locale may be removed from the form. Defaults to true. */
+    readonly removable?: boolean;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
 /** Arbitrary, JSON-serializable data preserved by every form-engine operation. */
 interface ExtensibleNode {
     readonly metadata?: Readonly<Record<string, JsonValue>>;
@@ -360,6 +386,16 @@ type FormSubmission<TMeta extends BaseSubmissionMetadata | undefined = undefined
 } : {
     readonly metadata: TMeta;
 });
+/** Clean network and persistence representation of a form submission. */
+interface FormSubmissionWire<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata> {
+    readonly id: string;
+    readonly formId: string;
+    readonly formVersion: number;
+    readonly values: Record<string, unknown>;
+    readonly metadata: TMeta;
+    readonly submittedAt: string;
+    readonly schemaRevision?: number;
+}
 interface CreateSubmissionInput<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata> {
     readonly id?: string;
     readonly formId: string;
@@ -600,9 +636,21 @@ interface ResponseAccumulatorOptions {
 }
 declare function createResponseAccumulator(schema: FormSchema, options?: ResponseAccumulatorOptions): ResponseAccumulator;
 declare function escapeCsvCell(value: string | number | boolean | null | undefined, neutralizeFormulas?: boolean): string;
-interface CsvExportOptions {
+interface CsvColumnDefinition<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata> {
+    readonly key: string;
+    readonly header: string;
+    readonly getValue: (submission: FormSubmission<TMeta>, schema: FormSchema) => string | number | boolean | null | undefined;
+}
+interface CsvExportOptions<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata> {
     readonly withBom?: boolean;
     readonly neutralizeFormulas?: boolean;
+    /** Alias for withBom used by the public export contract. */
+    readonly useBom?: boolean;
+    /** Alias for neutralizeFormulas used by the public export contract. */
+    readonly preventFormulaInjection?: boolean;
+    readonly customColumns?: readonly CsvColumnDefinition<TMeta>[];
+    readonly includePiiStatus?: boolean;
+    readonly includeLocale?: boolean;
 }
 interface CsvColumnDef {
     readonly header: string;
@@ -629,6 +677,45 @@ interface NodeWritableStream {
 declare function pipeResponsesToCsvStream(schema: FormSchema, submissions: AsyncIterable<AccumulatorResponse>, writable: WritableStream<Uint8Array> | NodeWritableStream, options?: StreamCsvOptions): Promise<void>;
 declare function exportResponsesToCsv(schema: FormSchema, responses: readonly FormSubmission[], options?: CsvExportOptions): string;
 
+interface SensitiveDataFinding {
+    readonly fieldId: string;
+    readonly type: string;
+    readonly start?: number;
+    readonly end?: number;
+    readonly matchedText?: string;
+    readonly maskedText?: string;
+}
+interface PrivacyEngine {
+    detect(schema: FormSchema, values: Record<string, unknown>): readonly SensitiveDataFinding[];
+}
+interface SubmissionValidationResult {
+    readonly valid: boolean;
+    readonly fieldErrors: Readonly<Record<string, string>>;
+    readonly formErrors: readonly string[];
+    readonly piiFindings?: readonly SensitiveDataFinding[];
+}
+declare function validateAnswers(schema: FormSchema, values: FormValues): AnswerValidationResult;
+declare function validatePageAnswers(schema: FormSchema, pageIndex: number, values: FormValues): AnswerValidationResult;
+declare function validateSubmission<TMeta extends BaseSubmissionMetadata | undefined = undefined>(schema: FormSchema, submission: FormSubmission<TMeta>, options?: {
+    readonly privacyEngine?: PrivacyEngine;
+}): SubmissionValidationResult;
+
+interface FormSubmissionSerializedError {
+    readonly code: "VALIDATION_FAILED" | "PII_CONFIRMATION_REQUIRED" | "SUBMISSION_BLOCKED" | "STORAGE_ERROR";
+    readonly messageKey: FormEngineTranslationKey | string;
+    readonly messageParams?: Readonly<Record<string, unknown>>;
+    readonly fieldErrors: Readonly<Record<string, string>>;
+    readonly formErrors: readonly string[];
+    readonly piiFindings?: readonly SensitiveDataFinding[];
+    readonly piiWarningAcknowledged?: boolean;
+}
+/** Error with a stable, JSON-serializable payload for RPC boundaries. */
+declare class FormSubmissionError extends Error {
+    readonly payload: FormSubmissionSerializedError;
+    constructor(payload: FormSubmissionSerializedError);
+    toJSON(): FormSubmissionSerializedError;
+}
+
 type FormEventType = "response.submitted" | "schema.updated";
 interface FormEvent<T = unknown> {
     readonly id: string;
@@ -772,12 +859,28 @@ interface ValidateFormSchemaOptions {
 declare function validateFormSchema(input: unknown, options?: ValidateFormSchemaOptions): SchemaValidationResult;
 declare function assertValidFormSchema(input: unknown): asserts input is FormSchema;
 
+/** Runtime schema for the JSON metadata carried by a submission wire payload. */
+declare const FormSubmissionMetadataSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+/** Runtime schema for the clean, alias-free submission wire format. */
+declare const FormSubmissionWireSchema: z.ZodObject<{
+    id: z.ZodString;
+    formId: z.ZodString;
+    formVersion: z.ZodNumber;
+    values: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    submittedAt: z.ZodString;
+    schemaRevision: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type FormSubmissionWireSchemaType = z.infer<typeof FormSubmissionWireSchema>;
+
 interface CreateSubmissionOptions<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata> extends ExtensibleNode {
     readonly id: string;
     readonly locale: string;
     readonly submittedAt: string;
     readonly metadata?: TMeta & Readonly<Record<string, JsonValue>>;
 }
+declare function toFormSubmissionWire<TMeta extends BaseSubmissionMetadata>(submission: FormSubmission<TMeta>): FormSubmissionWire<TMeta>;
+declare function toFormSubmissionWire(submission: FormSubmission): FormSubmissionWire;
 declare function createSubmission(schema: FormSchema, values: FormValues, options: CreateSubmissionOptions): FormSubmission;
 declare function createSubmission<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata>(schema: FormSchema, values: FormValues, options: CreateSubmissionOptions<TMeta>): FormSubmission<TMeta>;
 declare function createSubmission<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata>(input: CreateSubmissionInput<TMeta>): FormSubmission<TMeta>;
@@ -897,29 +1000,6 @@ declare function populateSchemaTranslations(schema: FormSchema, targetLocales: r
 }>;
 declare function resolveFormTranslation(schema: FormSchema, adapter: AsyncTranslationAdapter, targetLocale: string, sourceLocale?: string): Promise<FormSchema>;
 
-interface SensitiveDataFinding {
-    readonly fieldId: string;
-    readonly type: string;
-    readonly start?: number;
-    readonly end?: number;
-    readonly matchedText?: string;
-    readonly maskedText?: string;
-}
-interface PrivacyEngine {
-    detect(schema: FormSchema, values: Record<string, unknown>): readonly SensitiveDataFinding[];
-}
-interface SubmissionValidationResult {
-    readonly valid: boolean;
-    readonly fieldErrors: Readonly<Record<string, string>>;
-    readonly formErrors: readonly string[];
-    readonly piiFindings?: readonly SensitiveDataFinding[];
-}
-declare function validateAnswers(schema: FormSchema, values: FormValues): AnswerValidationResult;
-declare function validatePageAnswers(schema: FormSchema, pageIndex: number, values: FormValues): AnswerValidationResult;
-declare function validateSubmission<TMeta extends BaseSubmissionMetadata | undefined = undefined>(schema: FormSchema, submission: FormSubmission<TMeta>, options?: {
-    readonly privacyEngine?: PrivacyEngine;
-}): SubmissionValidationResult;
-
 declare function isDisplayConditionGroupSatisfied(group: DisplayConditionGroup, currentAnswers: Readonly<Record<string, unknown>>): boolean;
 declare function isQuestionVisible(question: FormField, currentAnswers: Readonly<Record<string, unknown>>): boolean;
 declare function isDisplayConditionSatisfied(condition: DisplayCondition | undefined, currentAnswers: Readonly<Record<string, unknown>>): boolean;
@@ -927,4 +1007,4 @@ declare function calculatePageVisibility(schema: FormSchema, currentAnswers: Rea
 declare function calculateFieldVisibility(schema: FormSchema, currentAnswers: Readonly<Record<string, unknown>>): Readonly<Record<string, boolean>>;
 declare function selectVisibleAnswers(schema: FormSchema, currentAnswers: FormValues): FormValues;
 
-export { type AccumulatorReport, type AccumulatorResponse, type AccumulatorSkipReason, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type BaseFieldConstraintRule, type BaseSubmissionMetadata, type BuilderTranslationKey, type CanonicalTranslationMetadata, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceFieldConstraintRule, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type CommitVersionTransitionOptions, type ConditionOperator, type ConditionValue, type CreateSubmissionInput, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnContext, type CsvColumnDef, type CsvExportOptions, type CursorPagingOptions, DEFAULT_FIELD_TYPE_DEFINITIONS, type DeleteDraftOptions, type DisplayCondition, type DisplayConditionGroup, type DisplayRule, EN_MESSAGES, type ExtensibleNode, type FieldConstraintRule, type FieldDisplayCondition, type FieldOption, type FieldType, type FieldTypeDefinition, type FormAnalytics, type FormEngineMessages, type FormEngineTranslationKey, type FormEngineTranslator, type FormEngineTranslatorOptions, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormSubmissionSettings, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type FormVersionTransitionPlan, JA_MESSAGES, type JsonValue, type KnownBuilderTranslationKey, type LegacyTranslationMetadata, type LocalizedText, type MigrateSchemaTranslationMetadataOptions, type MultiSelectField, type NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PaginatedResult, type PaginationIteratorOptions, type PopulateTranslationOptions, type PopulateTranslationsOptions, type PrivacyEngine, type PublishDraftOptions, type PublishDraftResult, type Question, type QuestionAggregate, type QuestionType, type RatingField, type RatingFieldConstraintRule, type RendererTranslationKey, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SanitizeSchemaOptions, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type SensitiveDataFinding, type StorageAdapter, type StorageCommitError, type StorageCursor, type StorageFilterCriteria, type StreamCsvOptions, type SubmissionCursorPayload, type SubmissionCursorValue, type SubmissionFilter, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type SubmissionValidationResult, type TextAnswerCursorPayload, type TextAnswerCursorValue, type TextAnswerItem, type TextAnswerPage, type TextAnswerPageQueryOptions, type TextField, type TextFieldConstraintRule, type TextQuestionAggregate, type TranslationAdapter, type TranslationMetadataMigrator, type TranslationMigrationContext, type TranslationProviderError, type TranslationReport, type TranslationSlot, type TranslationStatus, type TranslationWorkspaceTranslationKey, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionContext, type VersionTransitionError, type VersionTransitionEvent, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, applyTransitionPlan, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, collectTranslationSlots, commitVersionTransition, computeSourceTextHash, createCloneTransitionPlan, createDeleteDraftTransitionPlan, createFormEngineTranslator, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeStorageSubmissionCursor, decodeStorageTextAnswerCursor, decodeSubmissionCursor, decodeTextAnswerCursor, deleteDraft, dispatchWebhook, encodeStorageSubmissionCursor, encodeStorageTextAnswerCursor, encodeSubmissionCursor, encodeTextAnswerCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, getTranslationStatus, isDisplayConditionGroupSatisfied, isDisplayConditionSatisfied, isManualTranslationMetadata, isQuestionVisible, iterateSubmissionPages, jsonValuesEqual, matchesSubmissionFilter, matchesSubmissionPageFilters, migrateSchemaTranslationMetadata, normalizeLocale, normalizeSubmissionPageSize, paginateWithFilter, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, removeLocaleFromSchema, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure, validateSubmission };
+export { type AccumulatorReport, type AccumulatorResponse, type AccumulatorSkipReason, type AggregationReport, type AggregationSkipReason, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type BaseFieldConstraintRule, type BaseSubmissionMetadata, type BuilderTranslationKey, type CanonicalTranslationMetadata, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceFieldConstraintRule, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type CommitVersionTransitionOptions, type ConditionOperator, type ConditionValue, type CreateSubmissionInput, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnContext, type CsvColumnDef, type CsvColumnDefinition, type CsvExportOptions, type CursorPagingOptions, DEFAULT_FIELD_TYPE_DEFINITIONS, type DeleteDraftOptions, type DisplayCondition, type DisplayConditionGroup, type DisplayRule, EN_MESSAGES, type ExtensibleNode, type FieldConstraintRule, type FieldDisplayCondition, type FieldOption, type FieldType, type FieldTypeDefinition, type FormAnalytics, type FormEngineMessages, type FormEngineTranslationKey, type FormEngineTranslator, type FormEngineTranslatorOptions, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, FormSubmissionError, FormSubmissionMetadataSchema, type FormSubmissionSerializedError, type FormSubmissionSettings, type FormSubmissionWire, FormSubmissionWireSchema, type FormSubmissionWireSchemaType, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type FormVersionTransitionPlan, JA_MESSAGES, type JsonValue, type KnownBuilderTranslationKey, type LegacyTranslationMetadata, type LocaleOption, type LocalizedText, type MigrateSchemaTranslationMetadataOptions, type MultiSelectField, type NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PaginatedResult, type PaginationIteratorOptions, type PopulateTranslationOptions, type PopulateTranslationsOptions, type PrivacyEngine, type PublishDraftOptions, type PublishDraftResult, type Question, type QuestionAggregate, type QuestionType, type RatingField, type RatingFieldConstraintRule, type RendererTranslationKey, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SanitizeSchemaOptions, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type SensitiveDataFinding, type StorageAdapter, type StorageCommitError, type StorageCursor, type StorageFilterCriteria, type StreamCsvOptions, type SubmissionCursorPayload, type SubmissionCursorValue, type SubmissionFilter, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type SubmissionValidationResult, type TextAnswerCursorPayload, type TextAnswerCursorValue, type TextAnswerItem, type TextAnswerPage, type TextAnswerPageQueryOptions, type TextField, type TextFieldConstraintRule, type TextQuestionAggregate, type TranslationAdapter, type TranslationMetadataMigrator, type TranslationMigrationContext, type TranslationProviderError, type TranslationReport, type TranslationSlot, type TranslationStatus, type TranslationWorkspaceDetailedKey, type TranslationWorkspaceTranslationKey, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionContext, type VersionTransitionError, type VersionTransitionEvent, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, applyTransitionPlan, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, collectTranslationSlots, commitVersionTransition, computeSourceTextHash, createCloneTransitionPlan, createDeleteDraftTransitionPlan, createFormEngineTranslator, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeStorageSubmissionCursor, decodeStorageTextAnswerCursor, decodeSubmissionCursor, decodeTextAnswerCursor, deleteDraft, dispatchWebhook, encodeStorageSubmissionCursor, encodeStorageTextAnswerCursor, encodeSubmissionCursor, encodeTextAnswerCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, getTranslationStatus, isDisplayConditionGroupSatisfied, isDisplayConditionSatisfied, isManualTranslationMetadata, isQuestionVisible, iterateSubmissionPages, jsonValuesEqual, matchesSubmissionFilter, matchesSubmissionPageFilters, migrateSchemaTranslationMetadata, normalizeLocale, normalizeSubmissionPageSize, paginateWithFilter, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, removeLocaleFromSchema, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, toFormSubmissionWire, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure, validateSubmission };

package/dist/index.js

@@ -1598,15 +1598,28 @@ function serializeUnknown(value) {
   if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
   return JSON.stringify(value);
 }
+function submissionWithMetadata(submission) {
+  return { ...submission, metadata: submission.metadata ?? {} };
+}
 async function* exportResponsesToCsvStream(schema, submissions, options = {}) {
   assertValidFormSchema(schema);
   const includeDefaultColumns = options.includeDefaultColumns ?? true;
   const customColumns = options.columns ?? [];
+  const contractColumns = options.customColumns ?? [];
+  const includeLocale = options.includeLocale ?? true;
+  const includePiiStatus = options.includePiiStatus ?? false;
   const headers = [
-    ...includeDefaultColumns ? ["submissionId", "submittedAt", "locale", ...schema.fields.map((field) => field.id)] : [],
-    ...customColumns.map((column) => column.header)
+    ...includeDefaultColumns ? [
+      "submissionId",
+      "submittedAt",
+      ...includeLocale ? ["locale"] : [],
+      ...includePiiStatus ? ["piiStatus"] : [],
+      ...schema.fields.map((field) => field.id)
+    ] : [],
+    ...customColumns.map((column) => column.header),
+    ...contractColumns.map((column) => column.header)
   ];
-  const neutralizeFormulas = options.neutralizeFormulas ?? true;
+  const neutralizeFormulas = options.preventFormulaInjection ?? options.neutralizeFormulas ?? true;
   const header = headers.map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",");
   yield `${options.withBom ?? true ? "\uFEFF" : ""}${header}`;
   for await (const submission of submissions) {
@@ -1615,10 +1628,12 @@ async function* exportResponsesToCsvStream(schema, submissions, options = {}) {
     const response = asFormResponse(submission);
     const answers = response.answers;
     const visible = selectVisibleAnswers(schema, answers);
+    const piiStatus = response.metadata?.piiConfirmed === true ? "confirmed" : "unconfirmed";
     const defaultCells = includeDefaultColumns ? [
       response.responseId,
       response.submittedAt,
-      response.sourceLocale ?? "",
+      ...includeLocale ? [response.sourceLocale ?? ""] : [],
+      ...includePiiStatus ? [piiStatus] : [],
       ...schema.fields.map((field) => serializeUnknown(visible[field.id]))
     ] : [];
     const context = {
@@ -1628,8 +1643,9 @@ async function* exportResponsesToCsvStream(schema, submissions, options = {}) {
       schema
     };
     const customCells = await Promise.all(customColumns.map((column) => column.getValue(context)));
+    const contractCells = "values" in submission ? contractColumns.map((column) => column.getValue(submissionWithMetadata(submission), schema)) : contractColumns.map(() => void 0);
     yield `\r
-${[...defaultCells, ...customCells].map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",")}`;
+${[...defaultCells, ...customCells, ...contractCells].map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",")}`;
   }
 }
 function isWebWritableStream(writable) {
@@ -1686,23 +1702,51 @@ function exportResponsesToCsv(schema, responses, options = {}) {
       throw new TypeError(`Submission ${response.id} does not match ${schema.id}@${schema.version}.`);
     }
   }
+  const includeLocale = options.includeLocale ?? true;
+  const includePiiStatus = options.includePiiStatus ?? false;
+  const customColumns = options.customColumns ?? [];
+  const headers = [
+    "submissionId",
+    "submittedAt",
+    ...includeLocale ? ["locale"] : [],
+    ...includePiiStatus ? ["piiStatus"] : [],
+    ...schema.fields.map((field) => field.id),
+    ...customColumns.map((column) => column.header)
+  ];
   const rows = [
-    ["submissionId", "submittedAt", "locale", ...schema.fields.map((field) => field.id)],
+    headers,
     ...responses.map((response) => {
       const visible = selectVisibleAnswers(schema, response.values);
+      const piiStatus = response.metadata?.piiConfirmed === true ? "confirmed" : "unconfirmed";
+      const submissionForCustomColumns = submissionWithMetadata(response);
       return [
         response.id,
         response.submittedAt,
-        response.locale,
-        ...schema.fields.map((field) => serializeValue(visible[field.id]))
+        ...includeLocale ? [response.locale] : [],
+        ...includePiiStatus ? [piiStatus] : [],
+        ...schema.fields.map((field) => serializeValue(visible[field.id])),
+        ...customColumns.map((column) => column.getValue(submissionForCustomColumns, schema))
       ];
     })
   ];
-  const neutralizeFormulas = options.neutralizeFormulas ?? true;
+  const neutralizeFormulas = options.preventFormulaInjection ?? options.neutralizeFormulas ?? true;
   const csv = rows.map((row) => row.map((cell) => escapeCsvCell(cell, neutralizeFormulas)).join(",")).join("\r\n");
-  return options.withBom ?? true ? `\uFEFF${csv}` : csv;
+  return options.useBom ?? options.withBom ?? true ? `\uFEFF${csv}` : csv;
 }
 
+// src/errors.ts
+var FormSubmissionError = class extends Error {
+  payload;
+  constructor(payload) {
+    super(payload.messageKey);
+    this.name = "FormSubmissionError";
+    this.payload = payload;
+  }
+  toJSON() {
+    return this.payload;
+  }
+};
+
 // src/events.ts
 function bytesToHex(bytes) {
   return [...new Uint8Array(bytes)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
@@ -2025,7 +2069,20 @@ var EN_MESSAGES = Object.freeze({
   "workspace.errors.maxLocalesExceeded": "The maximum number of locales ({{max}}) has been reached.",
   "workspace.errors.readOnly": "This workspace is read-only.",
   "workspace.errors.adapterNotConfigured": "A translation adapter is not configured.",
-  "workspace.errors.translationFailed": "Translation failed."
+  "workspace.errors.translationFailed": "Translation failed.",
+  "workspace.header.title": "Translation workspace",
+  "workspace.header.sourceLocale": "Source language",
+  "workspace.header.targetLocale": "Target language",
+  "workspace.header.translateAll": "Translate all",
+  "workspace.header.progress": "{{translated}}/{{total}} translated ({{percent}}%)",
+  "workspace.slot.sourceText": "Source",
+  "workspace.slot.translatedText": "Translation",
+  "workspace.slot.translateSingle": "Translate this slot",
+  "workspace.slot.revertManual": "Revert manual translation",
+  "workspace.confirm.removeLocaleTitle": "Remove language?",
+  "workspace.confirm.removeLocaleMessage": "This will remove {{locale}} and its translations.",
+  "workspace.empty.noTargetLocales": "No target languages are configured.",
+  "workspace.empty.noSlotsToTranslate": "There are no translation slots for this language."
 });
 
 // src/i18n/catalogs/ja.ts
@@ -2197,7 +2254,20 @@ var JA_MESSAGES = Object.freeze({
   "workspace.errors.maxLocalesExceeded": "\u767B\u9332\u53EF\u80FD\u306A\u6700\u5927\u8A00\u8A9E\u6570 ({{max}}) \u306B\u9054\u3057\u307E\u3057\u305F\u3002",
   "workspace.errors.readOnly": "\u8AAD\u307F\u53D6\u308A\u5C02\u7528\u30E2\u30FC\u30C9\u306E\u305F\u3081\u5909\u66F4\u3067\u304D\u307E\u305B\u3093\u3002",
   "workspace.errors.adapterNotConfigured": "\u7FFB\u8A33\u30A2\u30C0\u30D7\u30BF\u30FC\u304C\u8A2D\u5B9A\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002",
-  "workspace.errors.translationFailed": "\u7FFB\u8A33\u51E6\u7406\u306B\u5931\u6557\u3057\u307E\u3057\u305F\u3002"
+  "workspace.errors.translationFailed": "\u7FFB\u8A33\u51E6\u7406\u306B\u5931\u6557\u3057\u307E\u3057\u305F\u3002",
+  "workspace.header.title": "\u591A\u8A00\u8A9E\u7FFB\u8A33\u30EF\u30FC\u30AF\u30B9\u30DA\u30FC\u30B9",
+  "workspace.header.sourceLocale": "\u5143\u8A00\u8A9E",
+  "workspace.header.targetLocale": "\u7FFB\u8A33\u8A00\u8A9E",
+  "workspace.header.translateAll": "\u4E00\u62EC\u81EA\u52D5\u7FFB\u8A33",
+  "workspace.header.progress": "{{translated}}/{{total}} \u7FFB\u8A33\u6E08\u307F ({{percent}}%)",
+  "workspace.slot.sourceText": "\u539F\u6587",
+  "workspace.slot.translatedText": "\u7FFB\u8A33\u6587",
+  "workspace.slot.translateSingle": "\u3053\u306E\u9805\u76EE\u3092\u7FFB\u8A33",
+  "workspace.slot.revertManual": "\u624B\u52D5\u7FFB\u8A33\u3092\u5143\u306B\u623B\u3059",
+  "workspace.confirm.removeLocaleTitle": "\u8A00\u8A9E\u3092\u524A\u9664\u3057\u307E\u3059\u304B\uFF1F",
+  "workspace.confirm.removeLocaleMessage": "{{locale}} \u3068\u305D\u306E\u7FFB\u8A33\u3092\u524A\u9664\u3057\u307E\u3059\u3002",
+  "workspace.empty.noTargetLocales": "\u7FFB\u8A33\u5148\u306E\u8A00\u8A9E\u304C\u8A2D\u5B9A\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002",
+  "workspace.empty.noSlotsToTranslate": "\u3053\u306E\u8A00\u8A9E\u306B\u306F\u7FFB\u8A33\u9805\u76EE\u304C\u3042\u308A\u307E\u305B\u3093\u3002"
 });
 
 // src/i18n/translator.ts
@@ -2486,6 +2556,19 @@ function matchesSubmissionPageFilters(submission, options) {
   );
 }
 
+// src/schemas/submission.zod.ts
+import { z } from "zod";
+var FormSubmissionMetadataSchema = z.record(z.string(), z.unknown());
+var FormSubmissionWireSchema = z.object({
+  id: z.string().min(1),
+  formId: z.string().min(1),
+  formVersion: z.number().int().positive(),
+  values: z.record(z.string(), z.unknown()),
+  metadata: FormSubmissionMetadataSchema,
+  submittedAt: z.string().datetime(),
+  schemaRevision: z.number().int().optional()
+});
+
 // src/validation.ts
 var DEFAULT_MESSAGES = {
   required: "validation.required",
@@ -2666,6 +2749,19 @@ function toFormValues(answers) {
 function isFormValue(value) {
   return value === void 0 || typeof value === "string" || typeof value === "number" || typeof value === "boolean" || Array.isArray(value) && value.every((item) => typeof item === "string");
 }
+function toFormSubmissionWire(submission) {
+  const { id, formId, formVersion, values, answers, metadata, submittedAt, schemaRevision } = submission;
+  const targetValues = values ?? answers ?? {};
+  return {
+    id,
+    formId,
+    formVersion,
+    values: { ...targetValues },
+    metadata: { ...metadata ?? {} },
+    submittedAt,
+    ...schemaRevision === void 0 ? {} : { schemaRevision }
+  };
+}
 function createSubmission(schemaOrInput, values, options) {
   if ("answers" in schemaOrInput) {
     const input = schemaOrInput;
@@ -3089,18 +3185,20 @@ var migrateSchemaTranslationMetadata = (schema, migratorOrOptions) => {
   };
 };
 var removeLocaleFromSchema = (schema, localeToRemove) => {
-  if (localeToRemove === schema.defaultLocale) {
+  const normalizedLocaleToRemove = normalizeLocale(localeToRemove) ?? localeToRemove;
+  const normalizedDefaultLocale = schema.defaultLocale === void 0 ? void 0 : normalizeLocale(schema.defaultLocale) ?? schema.defaultLocale;
+  if (normalizedLocaleToRemove === normalizedDefaultLocale) {
     throw new Error(`Cannot remove defaultLocale: ${localeToRemove}`);
   }
-  const form = removeLocalizedNodeLocale(schema, localeToRemove);
+  const form = removeLocalizedNodeLocale(schema, normalizedLocaleToRemove);
   const fields = schema.fields.map((field) => {
-    const localizedField = removeLocalizedNodeLocale(field, localeToRemove);
+    const localizedField = removeLocalizedNodeLocale(field, normalizedLocaleToRemove);
     if (!("options" in localizedField)) return localizedField;
     return {
       ...localizedField,
       options: localizedField.options.map((option) => {
-        const translations = removeLocaleRecord(option.translations, localeToRemove);
-        const translationMetadata = removeLocaleRecord(option.translationMetadata, localeToRemove);
+        const translations = removeLocaleRecord(option.translations, normalizedLocaleToRemove);
+        const translationMetadata = removeLocaleRecord(option.translationMetadata, normalizedLocaleToRemove);
         const { translations: _translations, translationMetadata: _translationMetadata, ...base } = option;
         return {
           ...base,
@@ -3110,10 +3208,12 @@ var removeLocaleFromSchema = (schema, localeToRemove) => {
       })
     };
   });
-  const pages = schema.pages?.map((page) => removeLocalizedNodeLocale(page, localeToRemove));
+  const pages = schema.pages?.map((page) => removeLocalizedNodeLocale(page, normalizedLocaleToRemove));
   return {
     ...form,
-    supportedLocales: (schema.supportedLocales ?? []).filter((locale) => locale !== localeToRemove),
+    supportedLocales: (schema.supportedLocales ?? []).filter(
+      (locale) => (normalizeLocale(locale) ?? locale) !== normalizedLocaleToRemove
+    ),
     fields,
     ...pages === void 0 ? {} : { pages }
   };
@@ -3571,6 +3671,9 @@ async function commitVersionTransition(options) {
 export {
   DEFAULT_FIELD_TYPE_DEFINITIONS,
   EN_MESSAGES,
+  FormSubmissionError,
+  FormSubmissionMetadataSchema,
+  FormSubmissionWireSchema,
   JA_MESSAGES,
   aggregateResponses,
   applyTransitionPlan,
@@ -3626,6 +3729,7 @@ export {
   resolveLocalizedSchema,
   sanitizeSchema,
   selectVisibleAnswers,
+  toFormSubmissionWire,
   transformFieldType,
   validateAnswers,
   validateFormSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/core",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "publishConfig": {
     "access": "public"
   },
@@ -38,6 +38,9 @@
     "validation",
     "typescript"
   ],
+  "dependencies": {
+    "zod": "^4.0.0"
+  },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",
     "check": "biome check . && tsc --noEmit",