@form-engine-ts/core 2.2.0 → 2.5.0

package/README.md

@@ -44,6 +44,12 @@ option, text, serialized-byte, allowed-type, and locale constraints. `allowedLoc
 locales, `maxLocales` limits their unique total, and contradictory required/allowed locale policies are reported.
 Required locales cover every source text that exists on the form, its fields, options, and pages.
 
+`collectSchemaLocales(schema)` scans registrations plus every form/page/field/option `translations` and
+`translationMetadata` key. Validation reports unregistered translation locales and applies `allowedLocales` and
+`maxLocales` to the complete collected set. `sanitizeSchema` purges unregistered locale content. Pass
+`{ policy: { allowedLocales, maxLocales } }` to `populateSchemaTranslations` to reject inadmissible targets before the
+translation adapter runs.
+
 Translation callbacks receive `nodeMetadata` and `existingTranslationMetadata` separately. The deprecated `metadata`
 slot property remains an alias for `nodeMetadata` during migration.
 
@@ -68,4 +74,16 @@ const submissions = await storage.listSubmissions("contact", 1, range);
 
 Results are ordered by `submittedAt`, then submission ID. Both boundaries are inclusive.
 
+## Versioning, incremental analytics, and paged storage
+
+`cloneVersionToDraft`, `publishDraft`, and `deleteDraft` implement revision-checked version transitions as pure functions.
+`createResponseAccumulator` incrementally counts choices, answered/unanswered values, and numeric summaries without retaining
+free-text bodies. Independent accumulators for the same schema can be merged, and `finalize()` matches `aggregateResponses`.
+
+`exportResponsesToCsvStream` accepts an `AsyncIterable`, emits the BOM/header and one chunk per response, and supports
+custom `CsvColumnDef` columns. Formula-injection neutralization applies to both default and custom columns.
+
+Adapters implementing `PagedSubmissionStorageAdapter` expose `listSubmissionPage(formId, options)`. The opaque Base64
+cursor combines `submittedAt` and response ID, so equal timestamps do not produce gaps or duplicates.
+
 See the [project documentation](https://github.com/nitta-a/form-engine-ts#readme) for the complete schema and API guide.

package/dist/index.cjs

@@ -22,18 +22,28 @@ var index_exports = {};
 __export(index_exports, {
   aggregateResponses: () => aggregateResponses,
   assertValidFormSchema: () => assertValidFormSchema,
+  assertVersionMutable: () => assertVersionMutable,
   calculateChoiceDistribution: () => calculateChoiceDistribution,
   calculateCrossTabulation: () => calculateCrossTabulation,
   calculateFieldVisibility: () => calculateFieldVisibility,
   calculateNumericSummary: () => calculateNumericSummary,
   calculatePageVisibility: () => calculatePageVisibility,
+  cloneVersionToDraft: () => cloneVersionToDraft,
+  collectSchemaLocales: () => collectSchemaLocales,
+  createResponseAccumulator: () => createResponseAccumulator,
   createSubmission: () => createSubmission,
+  decodeSubmissionCursor: () => decodeSubmissionCursor,
+  deleteDraft: () => deleteDraft,
   dispatchWebhook: () => dispatchWebhook,
+  encodeSubmissionCursor: () => encodeSubmissionCursor,
   escapeCsvCell: () => escapeCsvCell,
   exportResponsesToCsv: () => exportResponsesToCsv,
+  exportResponsesToCsvStream: () => exportResponsesToCsvStream,
   isDisplayConditionSatisfied: () => isDisplayConditionSatisfied,
   isQuestionVisible: () => isQuestionVisible,
+  normalizeSubmissionPageSize: () => normalizeSubmissionPageSize,
   populateSchemaTranslations: () => populateSchemaTranslations,
+  publishDraft: () => publishDraft,
   resolveFormTranslation: () => resolveFormTranslation,
   resolveLocalizedSchema: () => resolveLocalizedSchema,
   sanitizeSchema: () => sanitizeSchema,
@@ -46,7 +56,95 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/policy.ts
+function collectRecordKeys(value, path, pathsByLocale) {
+  for (const locale of Object.keys(value ?? {})) {
+    const paths = pathsByLocale.get(locale) ?? [];
+    paths.push(`${path}.${locale}`);
+    pathsByLocale.set(locale, paths);
+  }
+}
+function collectSchemaLocales(schema) {
+  const pathsByLocale = /* @__PURE__ */ new Map();
+  collectRecordKeys(schema.translations, "translations", pathsByLocale);
+  collectRecordKeys(schema.translationMetadata, "translationMetadata", pathsByLocale);
+  schema.fields.forEach((field, fieldIndex) => {
+    collectRecordKeys(field.translations, `fields[${fieldIndex}].translations`, pathsByLocale);
+    collectRecordKeys(field.translationMetadata, `fields[${fieldIndex}].translationMetadata`, pathsByLocale);
+    if (!("options" in field)) return;
+    field.options.forEach((option, optionIndex) => {
+      collectRecordKeys(
+        option.translations,
+        `fields[${fieldIndex}].options[${optionIndex}].translations`,
+        pathsByLocale
+      );
+      collectRecordKeys(
+        option.translationMetadata,
+        `fields[${fieldIndex}].options[${optionIndex}].translationMetadata`,
+        pathsByLocale
+      );
+    });
+  });
+  schema.pages?.forEach((page, pageIndex) => {
+    collectRecordKeys(page.translations, `pages[${pageIndex}].translations`, pathsByLocale);
+    collectRecordKeys(page.translationMetadata, `pages[${pageIndex}].translationMetadata`, pathsByLocale);
+  });
+  const translationLocales = new Set(pathsByLocale.keys());
+  const allUniqueLocales = /* @__PURE__ */ new Set([
+    ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
+    ...schema.supportedLocales ?? [],
+    ...translationLocales
+  ]);
+  return {
+    ...schema.defaultLocale === void 0 ? {} : { defaultLocale: schema.defaultLocale },
+    supportedLocales: schema.supportedLocales ?? [],
+    translationLocales,
+    allUniqueLocales,
+    translationLocalePaths: pathsByLocale
+  };
+}
+
 // src/sanitization.ts
+function registeredEntries(value, registeredLocales) {
+  if (value === void 0) return void 0;
+  const entries = Object.entries(value).filter(([locale]) => registeredLocales.has(locale));
+  return entries.length === 0 ? void 0 : Object.fromEntries(entries);
+}
+function sanitizeNodeLocales(node, registeredLocales) {
+  const { translationMetadata: _translationMetadata, ...base } = node;
+  const translationMetadata = registeredEntries(node.translationMetadata, registeredLocales);
+  return {
+    ...base,
+    ...translationMetadata === void 0 ? {} : { translationMetadata }
+  };
+}
+function sanitizeOptionLocales(option, registeredLocales) {
+  const { translations: _translations, ...base } = sanitizeNodeLocales(option, registeredLocales);
+  const translations = registeredEntries(option.translations, registeredLocales);
+  return { ...base, ...translations === void 0 ? {} : { translations } };
+}
+function sanitizeFieldLocales(field, registeredLocales) {
+  const localizedNode = sanitizeNodeLocales(field, registeredLocales);
+  const { translations: _translations, ...base } = localizedNode;
+  const translations = registeredEntries(field.translations, registeredLocales);
+  const localized = {
+    ...base,
+    ...translations === void 0 ? {} : { translations }
+  };
+  if (!("options" in localizedNode)) return localized;
+  const { translations: _choiceTranslations, ...choiceBase } = localizedNode;
+  return {
+    ...choiceBase,
+    ...translations === void 0 ? {} : { translations },
+    options: localizedNode.options.map((option) => sanitizeOptionLocales(option, registeredLocales))
+  };
+}
+function sanitizePageLocales(page, registeredLocales) {
+  const localizedNode = sanitizeNodeLocales(page, registeredLocales);
+  const { translations: _translations, ...base } = localizedNode;
+  const translations = registeredEntries(page.translations, registeredLocales);
+  return { ...base, ...translations === void 0 ? {} : { translations } };
+}
 function cyclicQuestionIds(fields) {
   const firstById = /* @__PURE__ */ new Map();
   for (const field of fields) {
@@ -133,8 +231,13 @@ function validateSchemaStructure(schema) {
 }
 function sanitizeSchema(schema) {
   const existingQuestionIds = new Set(schema.fields.map((field) => field.id));
+  const registeredLocales = /* @__PURE__ */ new Set([
+    ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
+    ...schema.supportedLocales ?? []
+  ]);
   const cyclic = cyclicQuestionIds(schema.fields);
-  const sanitizedFields = schema.fields.map((field) => {
+  const sanitizedFields = schema.fields.map((sourceField) => {
+    const field = sanitizeFieldLocales(sourceField, registeredLocales);
     const sourceId = field.displayCondition?.questionId;
     if (sourceId === void 0 || existingQuestionIds.has(sourceId) && sourceId !== field.id && !cyclic.has(field.id)) {
       return field;
@@ -142,15 +245,19 @@ function sanitizeSchema(schema) {
     const { displayCondition: _displayCondition, ...sanitized } = field;
     return sanitized;
   });
+  const localizedSchema = sanitizeNodeLocales(schema, registeredLocales);
+  const { translations: _translations, ...schemaWithoutLocaleContent } = localizedSchema;
+  const translations = registeredEntries(schema.translations, registeredLocales);
   const base = {
-    ...schema,
+    ...schemaWithoutLocaleContent,
+    ...translations === void 0 ? {} : { translations },
     fields: sanitizedFields
   };
   if (schema.pages === void 0) return base;
   const assigned = /* @__PURE__ */ new Set();
-  const pages = schema.pages.map((page) => ({
-    ...page,
-    questionIds: page.questionIds.filter((id) => {
+  const pages = schema.pages.map((sourcePage) => ({
+    ...sanitizePageLocales(sourcePage, registeredLocales),
+    questionIds: sourcePage.questionIds.filter((id) => {
       if (!existingQuestionIds.has(id) || assigned.has(id)) return false;
       assigned.add(id);
       return true;
@@ -554,31 +661,38 @@ function validatePolicy(schema, policy, issues) {
       }
     }
   }
-  const registeredLocales = [
-    .../* @__PURE__ */ new Set([
-      ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
-      ...schema.supportedLocales ?? []
-    ])
-  ];
-  if (policy.allowedLocales !== void 0) {
-    if (schema.defaultLocale !== void 0 && !policy.allowedLocales.includes(schema.defaultLocale)) {
+  const collectedLocales = collectSchemaLocales(schema);
+  const registeredLocales = /* @__PURE__ */ new Set([
+    ...schema.defaultLocale === void 0 ? [] : [schema.defaultLocale],
+    ...schema.supportedLocales ?? []
+  ]);
+  for (const locale of collectedLocales.translationLocales) {
+    if (registeredLocales.has(locale)) continue;
+    for (const path of collectedLocales.translationLocalePaths.get(locale) ?? []) {
       issue(
         issues,
-        "defaultLocale",
-        "disallowed_locale",
-        `Locale ${schema.defaultLocale} is not allowed by the form policy.`
+        path,
+        "unregistered_translation_locale",
+        `Translation locale ${locale} is not registered by defaultLocale or supportedLocales.`
       );
     }
+  }
+  if (policy.allowedLocales !== void 0) {
+    const pathsByLocale = /* @__PURE__ */ new Map();
+    if (schema.defaultLocale !== void 0) pathsByLocale.set(schema.defaultLocale, ["defaultLocale"]);
     schema.supportedLocales?.forEach((locale, index) => {
-      if (!policy.allowedLocales?.includes(locale)) {
-        issue(
-          issues,
-          `supportedLocales[${index}]`,
-          "disallowed_locale",
-          `Locale ${locale} is not allowed by the form policy.`
-        );
-      }
+      pathsByLocale.set(locale, [...pathsByLocale.get(locale) ?? [], `supportedLocales[${index}]`]);
     });
+    for (const [locale, paths] of collectedLocales.translationLocalePaths) {
+      pathsByLocale.set(locale, [...pathsByLocale.get(locale) ?? [], ...paths]);
+    }
+    for (const [locale, paths] of pathsByLocale) {
+      if (!policy.allowedLocales.includes(locale)) {
+        for (const path of paths) {
+          issue(issues, path, "disallowed_locale", `Locale ${locale} is not allowed by the form policy.`);
+        }
+      }
+    }
     for (const locale of policy.requiredLocales ?? []) {
       if (!policy.allowedLocales.includes(locale)) {
         issue(
@@ -590,7 +704,7 @@ function validatePolicy(schema, policy, issues) {
       }
     }
   }
-  if (policy.maxLocales !== void 0 && registeredLocales.length > policy.maxLocales) {
+  if (policy.maxLocales !== void 0 && collectedLocales.allUniqueLocales.size > policy.maxLocales) {
     issue(issues, "supportedLocales", "max_locales_exceeded", `At most ${policy.maxLocales} locales are allowed.`);
   }
   for (const locale of policy.requiredLocales ?? []) addRequiredTranslationIssues(schema, locale, issues);
@@ -986,6 +1100,152 @@ function aggregateResponses(schema, submissions) {
     questions: schema.fields.map((field) => aggregateField(schema, field, submissions))
   };
 }
+function responseValues(submission) {
+  return "values" in submission ? submission.values : submission.answers;
+}
+function responseIdentifier(submission) {
+  return "id" in submission ? submission.id : submission.responseId;
+}
+function responseMismatch(schema, submission) {
+  if (submission.formId !== schema.id) {
+    return `Submission ${responseIdentifier(submission)} does not match form ${schema.id}.`;
+  }
+  if ("formVersion" in submission && submission.formVersion !== schema.version) {
+    return `Submission ${responseIdentifier(submission)} does not match ${schema.id}@${schema.version}.`;
+  }
+  return void 0;
+}
+var IncrementalResponseAccumulator = class _IncrementalResponseAccumulator {
+  #schema;
+  #mode;
+  #fields;
+  #submissionCount = 0;
+  constructor(schema, options) {
+    assertValidFormSchema(schema);
+    this.#schema = JSON.parse(JSON.stringify(schema));
+    this.#mode = options.mode ?? "strict";
+    this.#fields = new Map(
+      schema.fields.map((field) => [
+        field.id,
+        {
+          answeredCount: 0,
+          total: 0,
+          minimum: null,
+          maximum: null,
+          trueCount: 0,
+          falseCount: 0,
+          optionCounts: new Map("options" in field ? field.options.map((option) => [option.id, 0]) : [])
+        }
+      ])
+    );
+  }
+  add(submission) {
+    const mismatch = responseMismatch(this.#schema, submission);
+    if (mismatch !== void 0 && this.#mode === "strict") return { success: false, error: mismatch };
+    const values = responseValues(submission);
+    const visibility = calculateFieldVisibility(this.#schema, values);
+    for (const field of this.#schema.fields) {
+      const accumulator = this.#fields.get(field.id);
+      if (accumulator === void 0) throw new Error(`Accumulator for ${field.id} is unavailable.`);
+      const candidate = values[field.id];
+      if (visibility[field.id] !== true || !valueIsValid(field, candidate)) continue;
+      accumulator.answeredCount += 1;
+      if ((field.type === "number" || field.type === "rating") && typeof candidate === "number") {
+        accumulator.total += candidate;
+        accumulator.minimum = accumulator.minimum === null ? candidate : Math.min(accumulator.minimum, candidate);
+        accumulator.maximum = accumulator.maximum === null ? candidate : Math.max(accumulator.maximum, candidate);
+      } else if (field.type === "checkbox") {
+        if (candidate === true) accumulator.trueCount += 1;
+        if (candidate === false) accumulator.falseCount += 1;
+      } else if ("options" in field) {
+        const selections = Array.isArray(candidate) ? candidate : typeof candidate === "string" ? [candidate] : [];
+        for (const selection of selections) {
+          accumulator.optionCounts.set(selection, (accumulator.optionCounts.get(selection) ?? 0) + 1);
+        }
+      }
+    }
+    this.#submissionCount += 1;
+    return { success: true };
+  }
+  addMany(submissions) {
+    for (const submission of submissions) {
+      const result = this.add(submission);
+      if (!result.success) throw new TypeError(result.error ?? "Submission could not be accumulated.");
+    }
+  }
+  merge(other) {
+    if (!(other instanceof _IncrementalResponseAccumulator)) {
+      throw new TypeError("Only form-engine response accumulators can be merged.");
+    }
+    if (other.#schema.id !== this.#schema.id || other.#schema.version !== this.#schema.version || JSON.stringify(other.#schema.fields) !== JSON.stringify(this.#schema.fields)) {
+      throw new TypeError("Response accumulators must use the same schema.");
+    }
+    this.#submissionCount += other.#submissionCount;
+    for (const [fieldId, source] of other.#fields) {
+      const target = this.#fields.get(fieldId);
+      if (target === void 0) throw new Error(`Accumulator for ${fieldId} is unavailable.`);
+      target.answeredCount += source.answeredCount;
+      target.total += source.total;
+      target.minimum = target.minimum === null ? source.minimum : source.minimum === null ? target.minimum : Math.min(target.minimum, source.minimum);
+      target.maximum = target.maximum === null ? source.maximum : source.maximum === null ? target.maximum : Math.max(target.maximum, source.maximum);
+      target.trueCount += source.trueCount;
+      target.falseCount += source.falseCount;
+      for (const [optionId, count] of source.optionCounts) {
+        target.optionCounts.set(optionId, (target.optionCounts.get(optionId) ?? 0) + count);
+      }
+    }
+    return this;
+  }
+  finalize() {
+    return {
+      formId: this.#schema.id,
+      formVersion: this.#schema.version,
+      submissionCount: this.#submissionCount,
+      questions: this.#schema.fields.map((field) => {
+        const accumulator = this.#fields.get(field.id);
+        if (accumulator === void 0) throw new Error(`Accumulator for ${field.id} is unavailable.`);
+        const base = {
+          fieldId: field.id,
+          answeredCount: accumulator.answeredCount,
+          unansweredCount: this.#submissionCount - accumulator.answeredCount
+        };
+        if (field.type === "text" || field.type === "textarea") return { ...base, kind: field.type };
+        if (field.type === "number" || field.type === "rating") {
+          return {
+            ...base,
+            kind: field.type,
+            minimum: accumulator.minimum,
+            maximum: accumulator.maximum,
+            average: accumulator.answeredCount === 0 ? null : accumulator.total / accumulator.answeredCount,
+            total: accumulator.total
+          };
+        }
+        if (field.type === "checkbox") {
+          return {
+            ...base,
+            kind: "checkbox",
+            trueCount: accumulator.trueCount,
+            falseCount: accumulator.falseCount,
+            truePercentageOfSubmissions: percentage(accumulator.trueCount, this.#submissionCount),
+            falsePercentageOfSubmissions: percentage(accumulator.falseCount, this.#submissionCount)
+          };
+        }
+        if (!("options" in field)) throw new TypeError(`Field ${field.id} cannot be aggregated.`);
+        return {
+          ...base,
+          kind: field.type,
+          options: field.options.map((option) => {
+            const count = accumulator.optionCounts.get(option.id) ?? 0;
+            return { id: option.id, count, percentageOfSubmissions: percentage(count, this.#submissionCount) };
+          })
+        };
+      })
+    };
+  }
+};
+function createResponseAccumulator(schema, options = {}) {
+  return new IncrementalResponseAccumulator(schema, options);
+}
 function escapeCsvCell(value, neutralizeFormulas = true) {
   if (value === null || value === void 0) return "";
   let stringValue = String(value);
@@ -1001,6 +1261,51 @@ function serializeValue(value) {
   if (value === void 0) return "";
   return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : JSON.stringify(value);
 }
+function asFormResponse(submission) {
+  if (!("values" in submission)) return submission;
+  return {
+    responseId: submission.id,
+    formId: submission.formId,
+    sourceLocale: submission.locale,
+    answers: submission.values,
+    submittedAt: submission.submittedAt,
+    ...submission.metadata === void 0 ? {} : { metadata: submission.metadata },
+    ...submission.translationMetadata === void 0 ? {} : { translationMetadata: submission.translationMetadata }
+  };
+}
+function serializeUnknown(value) {
+  if (value === null || value === void 0) return "";
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+  return JSON.stringify(value);
+}
+async function* exportResponsesToCsvStream(schema, submissions, options = {}) {
+  assertValidFormSchema(schema);
+  const includeDefaultColumns = options.includeDefaultColumns ?? true;
+  const customColumns = options.columns ?? [];
+  const headers = [
+    ...includeDefaultColumns ? ["submissionId", "submittedAt", "locale", ...schema.fields.map((field) => field.id)] : [],
+    ...customColumns.map((column) => column.header)
+  ];
+  const neutralizeFormulas = options.neutralizeFormulas ?? true;
+  const header = headers.map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",");
+  yield `${options.withBom ?? true ? "\uFEFF" : ""}${header}`;
+  for await (const submission of submissions) {
+    const mismatch = responseMismatch(schema, submission);
+    if (mismatch !== void 0) throw new TypeError(mismatch);
+    const response = asFormResponse(submission);
+    const answers = response.answers;
+    const visible = selectVisibleAnswers(schema, answers);
+    const defaultCells = includeDefaultColumns ? [
+      response.responseId,
+      response.submittedAt,
+      response.sourceLocale ?? "",
+      ...schema.fields.map((field) => serializeUnknown(visible[field.id]))
+    ] : [];
+    const customCells = customColumns.map((column) => column.getValue(response));
+    yield `\r
+${[...defaultCells, ...customCells].map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",")}`;
+  }
+}
 function exportResponsesToCsv(schema, responses, options = {}) {
   assertValidFormSchema(schema);
   for (const response of responses) {
@@ -1118,6 +1423,61 @@ function transformFieldType(field, nextType) {
   return { ...common, type: nextType, options };
 }
 
+// src/pagination.ts
+var BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function encodeBase64(bytes) {
+  let result = "";
+  for (let index = 0; index < bytes.length; index += 3) {
+    const first = bytes[index] ?? 0;
+    const second = bytes[index + 1] ?? 0;
+    const third = bytes[index + 2] ?? 0;
+    const combined = first << 16 | second << 8 | third;
+    result += BASE64_ALPHABET[combined >> 18 & 63] ?? "";
+    result += BASE64_ALPHABET[combined >> 12 & 63] ?? "";
+    result += index + 1 < bytes.length ? BASE64_ALPHABET[combined >> 6 & 63] ?? "" : "=";
+    result += index + 2 < bytes.length ? BASE64_ALPHABET[combined & 63] ?? "" : "=";
+  }
+  return result;
+}
+function decodeBase64(value) {
+  if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+    throw new TypeError("cursor must be a valid Base64 token.");
+  }
+  const bytes = [];
+  for (let index = 0; index < value.length; index += 4) {
+    const characters = value.slice(index, index + 4);
+    const sextets = [...characters].map((character) => character === "=" ? 0 : BASE64_ALPHABET.indexOf(character));
+    const combined = (sextets[0] ?? 0) << 18 | (sextets[1] ?? 0) << 12 | (sextets[2] ?? 0) << 6 | (sextets[3] ?? 0);
+    bytes.push(combined >> 16 & 255);
+    if (characters[2] !== "=") bytes.push(combined >> 8 & 255);
+    if (characters[3] !== "=") bytes.push(combined & 255);
+  }
+  return new Uint8Array(bytes);
+}
+function encodeSubmissionCursor(value) {
+  if (value.submittedAt.length === 0 || value.responseId.length === 0) {
+    throw new TypeError("Cursor values must not be empty.");
+  }
+  return encodeBase64(new TextEncoder().encode(JSON.stringify(value)));
+}
+function decodeSubmissionCursor(cursor) {
+  try {
+    const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(decodeBase64(cursor)));
+    if (typeof parsed !== "object" || parsed === null || !("submittedAt" in parsed) || typeof parsed.submittedAt !== "string" || parsed.submittedAt.length === 0 || !("responseId" in parsed) || typeof parsed.responseId !== "string" || parsed.responseId.length === 0) {
+      throw new TypeError("cursor payload is invalid.");
+    }
+    return { submittedAt: parsed.submittedAt, responseId: parsed.responseId };
+  } catch (cause) {
+    if (cause instanceof TypeError && cause.message === "cursor payload is invalid.") throw cause;
+    throw new TypeError("cursor must be a valid form-engine cursor.", { cause });
+  }
+}
+function normalizeSubmissionPageSize(pageSize, fallback = 100) {
+  const value = pageSize ?? fallback;
+  if (!Number.isSafeInteger(value) || value < 1) throw new TypeError("pageSize must be a positive safe integer.");
+  return value;
+}
+
 // src/validation.ts
 var DEFAULT_MESSAGES = {
   required: "validation.required",
@@ -1493,6 +1853,18 @@ function resolveLocalizedSchema(schema, targetLocale) {
 async function populateSchemaTranslations(schema, targetLocales, adapter, options = {}) {
   assertValidFormSchema(schema);
   const locales = [...new Set(targetLocales.filter((locale) => locale.length > 0 && locale !== schema.defaultLocale))];
+  const allowedLocales = options.policy?.allowedLocales;
+  const collectedLocales = collectSchemaLocales(schema);
+  const disallowedLocale = [...collectedLocales.allUniqueLocales, ...locales].find(
+    (locale) => allowedLocales !== void 0 && !allowedLocales.includes(locale)
+  );
+  if (disallowedLocale !== void 0) {
+    throw new RangeError(`Translation locale ${disallowedLocale} is not allowed by the form policy.`);
+  }
+  const projectedLocales = /* @__PURE__ */ new Set([...collectedLocales.allUniqueLocales, ...locales]);
+  if (options.policy?.maxLocales !== void 0 && projectedLocales.size > options.policy.maxLocales) {
+    throw new RangeError(`At most ${options.policy.maxLocales} locales are allowed by the form policy.`);
+  }
   const updatedSlots = [];
   const skippedSlots = [];
   let result = schema;
@@ -1541,22 +1913,125 @@ async function resolveFormTranslation(schema, adapter, targetLocale, sourceLocal
   );
   return resolveLocalizedSchema(populated.schema, targetLocale);
 }
+
+// src/versioning.ts
+function validateState(state) {
+  if (state.formId.trim().length === 0) throw new TypeError("formId must not be empty.");
+  if (!Number.isSafeInteger(state.nextVersion) || state.nextVersion < 1) {
+    throw new TypeError("nextVersion must be a positive safe integer.");
+  }
+  if (!Number.isSafeInteger(state.revision) || state.revision < 0) {
+    throw new TypeError("revision must be a non-negative safe integer.");
+  }
+}
+function cloneVersionToDraft(state, sourceSchema, options = {}) {
+  validateState(state);
+  if (sourceSchema.id !== state.formId) throw new TypeError("sourceSchema.id must match state.formId.");
+  if (state.draftVersion !== void 0) {
+    return { success: false, error: { type: "draft_already_exists", currentDraftVersion: state.draftVersion } };
+  }
+  const maxVersions = options.maxVersions ?? Number.MAX_SAFE_INTEGER;
+  if (!Number.isSafeInteger(maxVersions) || maxVersions < 1) {
+    throw new TypeError("maxVersions must be a positive safe integer.");
+  }
+  if (state.nextVersion > maxVersions) {
+    return { success: false, error: { type: "max_version_exceeded", max: maxVersions } };
+  }
+  const version = state.nextVersion;
+  return {
+    success: true,
+    value: {
+      nextState: {
+        ...state,
+        draftVersion: version,
+        nextVersion: version + 1,
+        revision: state.revision + 1
+      },
+      draftSchema: { ...sourceSchema, version }
+    }
+  };
+}
+function publishDraft(state, draftSchema, options = {}) {
+  validateState(state);
+  if (options.expectedRevision !== void 0 && options.expectedRevision !== state.revision) {
+    return {
+      success: false,
+      error: {
+        type: "revision_conflict",
+        expectedRevision: options.expectedRevision,
+        actualRevision: state.revision
+      }
+    };
+  }
+  if (state.draftVersion === void 0 || draftSchema.id !== state.formId || draftSchema.version !== state.draftVersion) {
+    return { success: false, error: { type: "draft_not_found" } };
+  }
+  if (options.validate?.(draftSchema) === false) throw new TypeError("Draft schema validation failed.");
+  const timestamp = options.timestamp ?? "1970-01-01T00:00:00.000Z";
+  if (!Number.isFinite(Date.parse(timestamp))) throw new TypeError("timestamp must be a valid date string.");
+  const archivedVersion = state.publishedVersion;
+  const { draftVersion: _draftVersion, ...stateWithoutDraft } = state;
+  return {
+    success: true,
+    value: {
+      nextState: {
+        ...stateWithoutDraft,
+        publishedVersion: draftSchema.version,
+        revision: state.revision + 1
+      },
+      publishedRecord: {
+        formId: state.formId,
+        version: draftSchema.version,
+        status: "published",
+        schema: draftSchema,
+        createdAt: timestamp,
+        publishedAt: timestamp
+      },
+      ...archivedVersion === void 0 ? {} : { archivedVersion }
+    }
+  };
+}
+function deleteDraft(state) {
+  validateState(state);
+  if (state.draftVersion === void 0) return { success: false, error: { type: "draft_not_found" } };
+  const { draftVersion: _draftVersion, ...stateWithoutDraft } = state;
+  return {
+    success: true,
+    value: { nextState: { ...stateWithoutDraft, revision: state.revision + 1 } }
+  };
+}
+function assertVersionMutable(status) {
+  if (status !== "draft") {
+    const error = { type: "version_immutable", status };
+    throw new TypeError(`A ${status} form version is immutable.`, { cause: error });
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   aggregateResponses,
   assertValidFormSchema,
+  assertVersionMutable,
   calculateChoiceDistribution,
   calculateCrossTabulation,
   calculateFieldVisibility,
   calculateNumericSummary,
   calculatePageVisibility,
+  cloneVersionToDraft,
+  collectSchemaLocales,
+  createResponseAccumulator,
   createSubmission,
+  decodeSubmissionCursor,
+  deleteDraft,
   dispatchWebhook,
+  encodeSubmissionCursor,
   escapeCsvCell,
   exportResponsesToCsv,
+  exportResponsesToCsvStream,
   isDisplayConditionSatisfied,
   isQuestionVisible,
+  normalizeSubmissionPageSize,
   populateSchemaTranslations,
+  publishDraft,
   resolveFormTranslation,
   resolveLocalizedSchema,
   sanitizeSchema,