@form-engine-ts/core 2.6.0 → 2.8.0

package/README.md

@@ -77,11 +77,16 @@ Results are ordered by `submittedAt`, then submission ID. Both boundaries are in
 ## Versioning, incremental analytics, and paged storage
 
 `cloneVersionToDraft`, asynchronous `publishDraft`, and `deleteDraft` implement revision-checked version transitions as
-pure functions.
+pure functions. `createCloneTransitionPlan`, `createPublishTransitionPlan`, and `createDeleteDraftTransitionPlan` produce
+complete persistence plans with the next state, affected records, and immutable audit events.
+Publishing when state already identifies a Published version requires its matching `currentPublishedRecord`; omission or
+a version mismatch returns the typed `missing_published_record` error. The resulting archive preserves the original
+schema, creation timestamp, and metadata.
 Clone/delete operations accept `expectedRevision`; cloning rejects non-published sources, publish validation failures are
 returned as typed `validation_failed` issues, and successful publishing archives only a supplied actual published record,
 preserving its schema and metadata. `createPublishTransitionPlan` returns complete records plus expected/next revisions for
-storage adapters implementing `VersionedFormStorageAdapter` to commit atomically.
+storage adapters implementing `VersionedFormStorageAdapter` to commit atomically. Versioned adapters expose state/record
+reads and return a typed `Result` from `commitVersionTransition`, including the actual revision on concurrency conflicts.
 `createResponseAccumulator` incrementally counts choices, answered/unanswered values, and numeric summaries without retaining
 free-text bodies. In lenient mode, mismatched responses are skipped and exposed by `addMany()` and `getReport()` instead of
 being included silently. Independent accumulators for the same schema can be merged, and `finalize()` matches
@@ -94,6 +99,9 @@ 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. `metadataFilters`
-and `filter` are applied before page sizing.
+and `filter` are applied before page sizing. `filter` accepts a composable `eq`/`in`/`range`/`exists` and/or AST; adapters
+may push supported nodes to their native query language while preserving identical client-side semantics. Adapters that
+implement `listTextAnswerPage` expose stable cursor pagination over individual text answers.
+`TextAnswerPageQueryOptions.fieldIds` can select multiple free-text fields for item-level paging.
 
 See the [project documentation](https://github.com/nitta-a/form-engine-ts#readme) for the complete schema and API guide.

package/dist/index.cjs

@@ -30,18 +30,24 @@ __export(index_exports, {
   calculatePageVisibility: () => calculatePageVisibility,
   cloneVersionToDraft: () => cloneVersionToDraft,
   collectSchemaLocales: () => collectSchemaLocales,
+  createCloneTransitionPlan: () => createCloneTransitionPlan,
+  createDeleteDraftTransitionPlan: () => createDeleteDraftTransitionPlan,
   createPublishTransitionPlan: () => createPublishTransitionPlan,
   createResponseAccumulator: () => createResponseAccumulator,
   createSubmission: () => createSubmission,
   decodeSubmissionCursor: () => decodeSubmissionCursor,
+  decodeTextAnswerCursor: () => decodeTextAnswerCursor,
   deleteDraft: () => deleteDraft,
   dispatchWebhook: () => dispatchWebhook,
   encodeSubmissionCursor: () => encodeSubmissionCursor,
+  encodeTextAnswerCursor: () => encodeTextAnswerCursor,
   escapeCsvCell: () => escapeCsvCell,
   exportResponsesToCsv: () => exportResponsesToCsv,
   exportResponsesToCsvStream: () => exportResponsesToCsvStream,
   isDisplayConditionSatisfied: () => isDisplayConditionSatisfied,
   isQuestionVisible: () => isQuestionVisible,
+  jsonValuesEqual: () => jsonValuesEqual,
+  matchesSubmissionFilter: () => matchesSubmissionFilter,
   matchesSubmissionPageFilters: () => matchesSubmissionPageFilters,
   normalizeSubmissionPageSize: () => normalizeSubmissionPageSize,
   pipeResponsesToCsvStream: () => pipeResponsesToCsvStream,
@@ -1565,6 +1571,24 @@ function decodeSubmissionCursor(cursor) {
     throw new TypeError("cursor must be a valid form-engine cursor.", { cause });
   }
 }
+function encodeTextAnswerCursor(value) {
+  if (value.responseId.length === 0 || value.fieldId.length === 0) {
+    throw new TypeError("Text answer cursor values must not be empty.");
+  }
+  return encodeBase64(new TextEncoder().encode(JSON.stringify(value)));
+}
+function decodeTextAnswerCursor(cursor) {
+  try {
+    const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(decodeBase64(cursor)));
+    if (typeof parsed !== "object" || parsed === null || !("responseId" in parsed) || typeof parsed.responseId !== "string" || parsed.responseId.length === 0 || !("fieldId" in parsed) || typeof parsed.fieldId !== "string" || parsed.fieldId.length === 0) {
+      throw new TypeError("text answer cursor payload is invalid.");
+    }
+    return { responseId: parsed.responseId, fieldId: parsed.fieldId };
+  } catch (cause) {
+    if (cause instanceof TypeError && cause.message === "text answer cursor payload is invalid.") throw cause;
+    throw new TypeError("cursor must be a valid text answer 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.");
@@ -1589,8 +1613,39 @@ function jsonValuesEqual(left, right) {
   const rightKeys = Object.keys(right);
   return leftKeys.length === rightKeys.length && leftKeys.every((key) => Object.hasOwn(right, key) && jsonValuesEqual(left[key], right[key]));
 }
+function readSubmissionPath(submission, path) {
+  if (path.length === 0 || path.split(".").some((part) => part.length === 0 || part === "__proto__" || part === "constructor")) {
+    return void 0;
+  }
+  let current = submission;
+  for (const part of path.split(".")) {
+    if (typeof current !== "object" || current === null || !Object.hasOwn(current, part)) return void 0;
+    current = current[part];
+  }
+  return current;
+}
+function compareRangeValue(value, boundary, direction) {
+  if (typeof value === "number" && typeof boundary === "number") {
+    return direction === "from" ? value >= boundary : value <= boundary;
+  }
+  if (typeof value === "string" && typeof boundary === "string") {
+    return direction === "from" ? value >= boundary : value <= boundary;
+  }
+  return false;
+}
+function matchesSubmissionFilter(submission, filter) {
+  if (filter.op === "and") return filter.filters.every((item) => matchesSubmissionFilter(submission, item));
+  if (filter.op === "or") return filter.filters.some((item) => matchesSubmissionFilter(submission, item));
+  const value = readSubmissionPath(submission, filter.path);
+  if (filter.op === "eq") return jsonValuesEqual(value, filter.value);
+  if (filter.op === "in") return filter.values.some((candidate) => jsonValuesEqual(value, candidate));
+  if (filter.op === "exists") return filter.value ? value !== void 0 : value === void 0;
+  return (filter.from === void 0 || compareRangeValue(value, filter.from, "from")) && (filter.to === void 0 || compareRangeValue(value, filter.to, "to"));
+}
 function matchesSubmissionPageFilters(submission, options) {
-  if (options.filter !== void 0 && !options.filter(submission)) return false;
+  if (options.filter !== void 0 && !(typeof options.filter === "function" ? options.filter(submission) : matchesSubmissionFilter(submission, options.filter))) {
+    return false;
+  }
   if (options.metadataFilters === void 0) return true;
   return Object.entries(options.metadataFilters).every(
     ([key, value]) => jsonValuesEqual(submission.metadata?.[key], value)
@@ -2049,6 +2104,21 @@ function validateState(state) {
     throw new TypeError("revision must be a non-negative safe integer.");
   }
 }
+function requireTimestamp(value, name) {
+  const timestamp = value ?? "1970-01-01T00:00:00.000Z";
+  if (!Number.isFinite(Date.parse(timestamp))) throw new TypeError(`${name} must be a valid date string.`);
+  return timestamp;
+}
+function transitionEvent(type, state, nextState, affectedVersions, occurredAt) {
+  return {
+    type,
+    formId: state.formId,
+    fromRevision: state.revision,
+    toRevision: nextState.revision,
+    affectedVersions,
+    occurredAt
+  };
+}
 function cloneVersionToDraft(state, sourceSchema, options = {}) {
   validateState(state);
   if (sourceSchema.id !== state.formId) throw new TypeError("sourceSchema.id must match state.formId.");
@@ -2092,16 +2162,61 @@ function cloneVersionToDraft(state, sourceSchema, options = {}) {
     }
   };
 }
+function createCloneTransitionPlan(state, sourceRecord, options = {}) {
+  if (sourceRecord.formId !== state.formId || sourceRecord.schema.id !== sourceRecord.formId || sourceRecord.schema.version !== sourceRecord.version || sourceRecord.status !== "published" && !options.allowedSourceVersions?.includes(sourceRecord.version)) {
+    return {
+      success: false,
+      error: {
+        type: "invalid_source_version",
+        requestedVersion: sourceRecord.version,
+        ...state.publishedVersion === void 0 ? {} : { publishedVersion: state.publishedVersion }
+      }
+    };
+  }
+  const result = cloneVersionToDraft(state, sourceRecord.schema, options);
+  if (!result.success) return result;
+  const timestamp = requireTimestamp(options.clonedAt, "clonedAt");
+  const draftRecord = {
+    formId: state.formId,
+    version: result.value.draftSchema.version,
+    status: "draft",
+    schema: result.value.draftSchema,
+    revision: 1,
+    createdFromVersion: sourceRecord.version,
+    createdAt: timestamp,
+    ...options.metadata === void 0 ? {} : { metadata: options.metadata }
+  };
+  return {
+    success: true,
+    value: {
+      nextState: result.value.nextState,
+      plan: {
+        formId: state.formId,
+        expectedRevision: options.expectedRevision ?? state.revision,
+        nextRevision: result.value.nextState.revision,
+        draftToCreate: draftRecord,
+        events: [transitionEvent("draft.created", state, result.value.nextState, [draftRecord.version], timestamp)],
+        nextVersion: result.value.nextState.nextVersion,
+        timestamp
+      }
+    }
+  };
+}
 function validatePublishedRecord(state, record) {
-  if (record === void 0) return;
-  if (record.formId !== state.formId || record.version !== state.publishedVersion || record.status !== "published" || record.schema.id !== record.formId || record.schema.version !== record.version) {
+  if (state.publishedVersion !== void 0 && record?.version !== state.publishedVersion) {
+    return {
+      success: false,
+      error: { type: "missing_published_record", expectedVersion: state.publishedVersion }
+    };
+  }
+  if (record === void 0) return void 0;
+  if (record.formId !== state.formId || record.status !== "published" || record.schema.id !== record.formId || record.schema.version !== record.version) {
     throw new TypeError("currentPublishedRecord must match the state's published version.");
   }
+  return void 0;
 }
 function transitionTimestamp(options) {
-  const timestamp = options.publishedAt ?? options.timestamp ?? "1970-01-01T00:00:00.000Z";
-  if (!Number.isFinite(Date.parse(timestamp))) throw new TypeError("publishedAt must be a valid date string.");
-  return timestamp;
+  return requireTimestamp(options.publishedAt ?? options.timestamp, "publishedAt");
 }
 async function publishDraft(state, draftSchema, options = {}) {
   validateState(state);
@@ -2110,7 +2225,8 @@ async function publishDraft(state, draftSchema, options = {}) {
   if (state.draftVersion === void 0 || draftSchema.id !== state.formId || draftSchema.version !== state.draftVersion) {
     return { success: false, error: { type: "draft_not_found" } };
   }
-  validatePublishedRecord(state, options.currentPublishedRecord);
+  const publishedRecordError = validatePublishedRecord(state, options.currentPublishedRecord);
+  if (publishedRecordError !== void 0) return publishedRecordError;
   const validation = await options.validate?.(draftSchema);
   if (validation === false || Array.isArray(validation) && validation.length > 0) {
     return {
@@ -2184,6 +2300,19 @@ async function createPublishTransitionPlan(state, draftRecord, options = {}) {
         draftToDeleteVersion: draftRecord.version,
         publishedRecordToSave,
         archivedRecordsToSave: result.value.archivedRecords,
+        events: [
+          ...result.value.archivedRecords.length === 0 ? [] : [
+            transitionEvent(
+              "version.archived",
+              state,
+              result.value.nextState,
+              result.value.archivedRecords.map((record) => record.version),
+              timestamp
+            )
+          ],
+          transitionEvent("version.published", state, result.value.nextState, [draftRecord.version], timestamp)
+        ],
+        nextVersion: result.value.nextState.nextVersion,
         timestamp
       }
     }
@@ -2200,6 +2329,29 @@ function deleteDraft(state, options = {}) {
     value: { nextState: { ...stateWithoutDraft, revision: state.revision + 1 } }
   };
 }
+function createDeleteDraftTransitionPlan(state, draftRecord, options = {}) {
+  if (draftRecord.formId !== state.formId || draftRecord.version !== state.draftVersion || draftRecord.status !== "draft" || draftRecord.schema.id !== state.formId || draftRecord.schema.version !== draftRecord.version) {
+    return { success: false, error: { type: "draft_not_found" } };
+  }
+  const result = deleteDraft(state, options);
+  if (!result.success) return result;
+  const timestamp = requireTimestamp(options.deletedAt, "deletedAt");
+  return {
+    success: true,
+    value: {
+      nextState: result.value.nextState,
+      plan: {
+        formId: state.formId,
+        expectedRevision: options.expectedRevision ?? state.revision,
+        nextRevision: result.value.nextState.revision,
+        draftToDeleteVersion: draftRecord.version,
+        events: [transitionEvent("draft.deleted", state, result.value.nextState, [draftRecord.version], timestamp)],
+        nextVersion: result.value.nextState.nextVersion,
+        timestamp
+      }
+    }
+  };
+}
 function assertVersionMutable(status) {
   if (status !== "draft") {
     const error = { type: "version_immutable", status };
@@ -2218,18 +2370,24 @@ function assertVersionMutable(status) {
   calculatePageVisibility,
   cloneVersionToDraft,
   collectSchemaLocales,
+  createCloneTransitionPlan,
+  createDeleteDraftTransitionPlan,
   createPublishTransitionPlan,
   createResponseAccumulator,
   createSubmission,
   decodeSubmissionCursor,
+  decodeTextAnswerCursor,
   deleteDraft,
   dispatchWebhook,
   encodeSubmissionCursor,
+  encodeTextAnswerCursor,
   escapeCsvCell,
   exportResponsesToCsv,
   exportResponsesToCsvStream,
   isDisplayConditionSatisfied,
   isQuestionVisible,
+  jsonValuesEqual,
+  matchesSubmissionFilter,
   matchesSubmissionPageFilters,
   normalizeSubmissionPageSize,
   pipeResponsesToCsvStream,

package/dist/index.d.cts

@@ -24,11 +24,22 @@ interface FormVersionState {
     readonly nextVersion: number;
     readonly revision: number;
 }
+interface VersionTransitionEvent {
+    readonly type: "draft.created" | "draft.deleted" | "version.published" | "version.archived";
+    readonly formId: string;
+    readonly fromRevision: number;
+    readonly toRevision: number;
+    readonly affectedVersions: readonly number[];
+    readonly occurredAt: string;
+}
 type VersionTransitionError = {
     readonly type: "draft_already_exists";
     readonly currentDraftVersion: number;
 } | {
     readonly type: "draft_not_found";
+} | {
+    readonly type: "missing_published_record";
+    readonly expectedVersion: number;
 } | {
     readonly type: "revision_conflict";
     readonly expectedRevision: number;
@@ -50,6 +61,8 @@ type VersionTransitionError = {
 interface CloneVersionOptions {
     readonly maxVersions?: number;
     readonly expectedRevision?: number;
+    readonly clonedAt?: string;
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
     /** Additional known published versions that may be used as a clone source. */
     readonly allowedSourceVersions?: readonly number[];
 }
@@ -63,6 +76,7 @@ interface PublishDraftOptions {
 }
 interface DeleteDraftOptions {
     readonly expectedRevision?: number;
+    readonly deletedAt?: string;
 }
 interface PublishDraftResult {
     readonly nextState: FormVersionState;
@@ -75,6 +89,10 @@ declare function cloneVersionToDraft(state: FormVersionState, sourceSchema: Form
     readonly nextState: FormVersionState;
     readonly draftSchema: FormSchema;
 }, VersionTransitionError>;
+declare function createCloneTransitionPlan(state: FormVersionState, sourceRecord: FormVersionRecord, options?: CloneVersionOptions): Result<{
+    readonly nextState: FormVersionState;
+    readonly plan: VersionTransitionPlan;
+}, VersionTransitionError>;
 declare function publishDraft(state: FormVersionState, draftSchema: FormSchema, options?: PublishDraftOptions): Promise<Result<PublishDraftResult, VersionTransitionError>>;
 declare function createPublishTransitionPlan(state: FormVersionState, draftRecord: FormVersionRecord, options?: PublishDraftOptions): Promise<Result<{
     readonly nextState: FormVersionState;
@@ -83,6 +101,10 @@ declare function createPublishTransitionPlan(state: FormVersionState, draftRecor
 declare function deleteDraft(state: FormVersionState, options?: DeleteDraftOptions): Result<{
     readonly nextState: FormVersionState;
 }, VersionTransitionError>;
+declare function createDeleteDraftTransitionPlan(state: FormVersionState, draftRecord: FormVersionRecord, options?: DeleteDraftOptions): Result<{
+    readonly nextState: FormVersionState;
+    readonly plan: VersionTransitionPlan;
+}, VersionTransitionError>;
 declare function assertVersionMutable(status: FormVersionStatus): void;
 
 type FieldType = "text" | "textarea" | "number" | "rating" | "select" | "multi-select" | "checkbox" | "radio";
@@ -257,9 +279,37 @@ interface SubmissionPageQueryOptions {
     readonly since?: string;
     readonly until?: string;
     readonly locale?: string;
-    readonly filter?: (submission: FormSubmission) => boolean;
+    readonly filter?: SubmissionFilter | ((submission: FormSubmission) => boolean);
+    /** @deprecated Prefer the generic filter AST. */
     readonly metadataFilters?: Readonly<Record<string, JsonValue>>;
 }
+interface TextAnswerPageQueryOptions extends SubmissionPageQueryOptions {
+    readonly fieldIds?: readonly string[];
+}
+type SubmissionFilter = {
+    readonly op: "eq";
+    readonly path: string;
+    readonly value: JsonValue;
+} | {
+    readonly op: "in";
+    readonly path: string;
+    readonly values: readonly JsonValue[];
+} | {
+    readonly op: "range";
+    readonly path: string;
+    readonly from?: JsonValue;
+    readonly to?: JsonValue;
+} | {
+    readonly op: "exists";
+    readonly path: string;
+    readonly value: boolean;
+} | {
+    readonly op: "and";
+    readonly filters: readonly SubmissionFilter[];
+} | {
+    readonly op: "or";
+    readonly filters: readonly SubmissionFilter[];
+};
 interface SubmissionPage {
     readonly items: readonly FormSubmission[];
     readonly nextCursor?: string;
@@ -267,6 +317,22 @@ interface SubmissionPage {
 }
 interface PagedSubmissionStorageAdapter extends FormStorageAdapter {
     listSubmissionPage(formId: string, options?: SubmissionPageQueryOptions): Promise<SubmissionPage>;
+    listTextAnswerPage?(formId: string, fieldIdOrOptions?: string | TextAnswerPageQueryOptions, options?: TextAnswerPageQueryOptions): Promise<TextAnswerPage>;
+}
+interface TextAnswerItem {
+    readonly responseId: string;
+    readonly formId: string;
+    readonly formVersion: number;
+    readonly fieldId: string;
+    readonly text: string;
+    readonly locale?: string;
+    readonly submittedAt: string;
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
+}
+interface TextAnswerPage {
+    readonly items: readonly TextAnswerItem[];
+    readonly nextCursor?: string;
+    readonly hasMore: boolean;
 }
 interface VersionTransitionPlan {
     readonly formId: string;
@@ -276,13 +342,32 @@ interface VersionTransitionPlan {
     readonly draftToDeleteVersion?: number;
     readonly publishedRecordToSave?: FormVersionRecord;
     readonly archivedRecordsToSave?: readonly FormVersionRecord[];
+    readonly events: readonly VersionTransitionEvent[];
+    /** The complete next state value used by persistent adapters. */
+    readonly nextVersion?: number;
     readonly timestamp: string;
 }
+type StorageCommitError = {
+    readonly type: "revision_conflict";
+    readonly expectedRevision: number;
+    readonly actualRevision?: number;
+} | {
+    readonly type: "draft_already_exists";
+    readonly currentDraftVersion: number;
+} | {
+    readonly type: "invalid_transition";
+    readonly message: string;
+} | {
+    readonly type: "storage_error";
+    readonly cause: unknown;
+};
 interface VersionedFormStorageAdapter extends FormStorageAdapter {
-    commitVersionTransition(plan: VersionTransitionPlan): Promise<{
-        readonly success: boolean;
-        readonly error?: string;
-    }>;
+    getVersionState(formId: string): Promise<FormVersionState | null>;
+    getVersionRecord(formId: string, version: number): Promise<FormVersionRecord | null>;
+    listVersionRecords(formId: string): Promise<readonly FormVersionRecord[]>;
+    commitVersionTransition(plan: VersionTransitionPlan): Promise<Result<{
+        readonly success: true;
+    }, StorageCommitError>>;
 }
 interface BaseQuestionAggregate {
     readonly fieldId: string;
@@ -442,9 +527,17 @@ interface SubmissionCursorValue {
     readonly submittedAt: string;
     readonly responseId: string;
 }
+interface TextAnswerCursorValue {
+    readonly responseId: string;
+    readonly fieldId: string;
+}
 declare function encodeSubmissionCursor(value: SubmissionCursorValue): string;
 declare function decodeSubmissionCursor(cursor: string): SubmissionCursorValue;
+declare function encodeTextAnswerCursor(value: TextAnswerCursorValue): string;
+declare function decodeTextAnswerCursor(cursor: string): TextAnswerCursorValue;
 declare function normalizeSubmissionPageSize(pageSize: number | undefined, fallback?: number): number;
+declare function jsonValuesEqual(left: JsonValue | undefined, right: JsonValue | undefined): boolean;
+declare function matchesSubmissionFilter(submission: FormSubmission, filter: SubmissionFilter): boolean;
 declare function matchesSubmissionPageFilters(submission: FormSubmission, options: Pick<SubmissionPageQueryOptions, "filter" | "metadataFilters">): boolean;
 
 interface CollectedLocales {
@@ -520,4 +613,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 CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnContext, type CsvColumnDef, type CsvExportOptions, type DeleteDraftOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type JsonValue, type LocalizedText, type MultiSelectField, type NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PopulateTranslationOptions, type PublishDraftOptions, type PublishDraftResult, type Question, type QuestionAggregate, type QuestionType, type RatingField, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type StreamCsvOptions, type SubmissionCursorValue, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionError, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeSubmissionCursor, deleteDraft, dispatchWebhook, encodeSubmissionCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, isDisplayConditionSatisfied, isQuestionVisible, matchesSubmissionPageFilters, normalizeSubmissionPageSize, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };
+export { type AccumulatorReport, type AccumulatorResponse, type AccumulatorSkipReason, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnContext, type CsvColumnDef, type CsvExportOptions, type DeleteDraftOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type JsonValue, type LocalizedText, type MultiSelectField, type NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PopulateTranslationOptions, type PublishDraftOptions, type PublishDraftResult, type Question, type QuestionAggregate, type QuestionType, type RatingField, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type StorageCommitError, type StreamCsvOptions, type SubmissionCursorValue, type SubmissionFilter, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type TextAnswerCursorValue, type TextAnswerItem, type TextAnswerPage, type TextAnswerPageQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionError, type VersionTransitionEvent, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, createCloneTransitionPlan, createDeleteDraftTransitionPlan, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeSubmissionCursor, decodeTextAnswerCursor, deleteDraft, dispatchWebhook, encodeSubmissionCursor, encodeTextAnswerCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, isDisplayConditionSatisfied, isQuestionVisible, jsonValuesEqual, matchesSubmissionFilter, matchesSubmissionPageFilters, normalizeSubmissionPageSize, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };

package/dist/index.d.ts

@@ -24,11 +24,22 @@ interface FormVersionState {
     readonly nextVersion: number;
     readonly revision: number;
 }
+interface VersionTransitionEvent {
+    readonly type: "draft.created" | "draft.deleted" | "version.published" | "version.archived";
+    readonly formId: string;
+    readonly fromRevision: number;
+    readonly toRevision: number;
+    readonly affectedVersions: readonly number[];
+    readonly occurredAt: string;
+}
 type VersionTransitionError = {
     readonly type: "draft_already_exists";
     readonly currentDraftVersion: number;
 } | {
     readonly type: "draft_not_found";
+} | {
+    readonly type: "missing_published_record";
+    readonly expectedVersion: number;
 } | {
     readonly type: "revision_conflict";
     readonly expectedRevision: number;
@@ -50,6 +61,8 @@ type VersionTransitionError = {
 interface CloneVersionOptions {
     readonly maxVersions?: number;
     readonly expectedRevision?: number;
+    readonly clonedAt?: string;
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
     /** Additional known published versions that may be used as a clone source. */
     readonly allowedSourceVersions?: readonly number[];
 }
@@ -63,6 +76,7 @@ interface PublishDraftOptions {
 }
 interface DeleteDraftOptions {
     readonly expectedRevision?: number;
+    readonly deletedAt?: string;
 }
 interface PublishDraftResult {
     readonly nextState: FormVersionState;
@@ -75,6 +89,10 @@ declare function cloneVersionToDraft(state: FormVersionState, sourceSchema: Form
     readonly nextState: FormVersionState;
     readonly draftSchema: FormSchema;
 }, VersionTransitionError>;
+declare function createCloneTransitionPlan(state: FormVersionState, sourceRecord: FormVersionRecord, options?: CloneVersionOptions): Result<{
+    readonly nextState: FormVersionState;
+    readonly plan: VersionTransitionPlan;
+}, VersionTransitionError>;
 declare function publishDraft(state: FormVersionState, draftSchema: FormSchema, options?: PublishDraftOptions): Promise<Result<PublishDraftResult, VersionTransitionError>>;
 declare function createPublishTransitionPlan(state: FormVersionState, draftRecord: FormVersionRecord, options?: PublishDraftOptions): Promise<Result<{
     readonly nextState: FormVersionState;
@@ -83,6 +101,10 @@ declare function createPublishTransitionPlan(state: FormVersionState, draftRecor
 declare function deleteDraft(state: FormVersionState, options?: DeleteDraftOptions): Result<{
     readonly nextState: FormVersionState;
 }, VersionTransitionError>;
+declare function createDeleteDraftTransitionPlan(state: FormVersionState, draftRecord: FormVersionRecord, options?: DeleteDraftOptions): Result<{
+    readonly nextState: FormVersionState;
+    readonly plan: VersionTransitionPlan;
+}, VersionTransitionError>;
 declare function assertVersionMutable(status: FormVersionStatus): void;
 
 type FieldType = "text" | "textarea" | "number" | "rating" | "select" | "multi-select" | "checkbox" | "radio";
@@ -257,9 +279,37 @@ interface SubmissionPageQueryOptions {
     readonly since?: string;
     readonly until?: string;
     readonly locale?: string;
-    readonly filter?: (submission: FormSubmission) => boolean;
+    readonly filter?: SubmissionFilter | ((submission: FormSubmission) => boolean);
+    /** @deprecated Prefer the generic filter AST. */
     readonly metadataFilters?: Readonly<Record<string, JsonValue>>;
 }
+interface TextAnswerPageQueryOptions extends SubmissionPageQueryOptions {
+    readonly fieldIds?: readonly string[];
+}
+type SubmissionFilter = {
+    readonly op: "eq";
+    readonly path: string;
+    readonly value: JsonValue;
+} | {
+    readonly op: "in";
+    readonly path: string;
+    readonly values: readonly JsonValue[];
+} | {
+    readonly op: "range";
+    readonly path: string;
+    readonly from?: JsonValue;
+    readonly to?: JsonValue;
+} | {
+    readonly op: "exists";
+    readonly path: string;
+    readonly value: boolean;
+} | {
+    readonly op: "and";
+    readonly filters: readonly SubmissionFilter[];
+} | {
+    readonly op: "or";
+    readonly filters: readonly SubmissionFilter[];
+};
 interface SubmissionPage {
     readonly items: readonly FormSubmission[];
     readonly nextCursor?: string;
@@ -267,6 +317,22 @@ interface SubmissionPage {
 }
 interface PagedSubmissionStorageAdapter extends FormStorageAdapter {
     listSubmissionPage(formId: string, options?: SubmissionPageQueryOptions): Promise<SubmissionPage>;
+    listTextAnswerPage?(formId: string, fieldIdOrOptions?: string | TextAnswerPageQueryOptions, options?: TextAnswerPageQueryOptions): Promise<TextAnswerPage>;
+}
+interface TextAnswerItem {
+    readonly responseId: string;
+    readonly formId: string;
+    readonly formVersion: number;
+    readonly fieldId: string;
+    readonly text: string;
+    readonly locale?: string;
+    readonly submittedAt: string;
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
+}
+interface TextAnswerPage {
+    readonly items: readonly TextAnswerItem[];
+    readonly nextCursor?: string;
+    readonly hasMore: boolean;
 }
 interface VersionTransitionPlan {
     readonly formId: string;
@@ -276,13 +342,32 @@ interface VersionTransitionPlan {
     readonly draftToDeleteVersion?: number;
     readonly publishedRecordToSave?: FormVersionRecord;
     readonly archivedRecordsToSave?: readonly FormVersionRecord[];
+    readonly events: readonly VersionTransitionEvent[];
+    /** The complete next state value used by persistent adapters. */
+    readonly nextVersion?: number;
     readonly timestamp: string;
 }
+type StorageCommitError = {
+    readonly type: "revision_conflict";
+    readonly expectedRevision: number;
+    readonly actualRevision?: number;
+} | {
+    readonly type: "draft_already_exists";
+    readonly currentDraftVersion: number;
+} | {
+    readonly type: "invalid_transition";
+    readonly message: string;
+} | {
+    readonly type: "storage_error";
+    readonly cause: unknown;
+};
 interface VersionedFormStorageAdapter extends FormStorageAdapter {
-    commitVersionTransition(plan: VersionTransitionPlan): Promise<{
-        readonly success: boolean;
-        readonly error?: string;
-    }>;
+    getVersionState(formId: string): Promise<FormVersionState | null>;
+    getVersionRecord(formId: string, version: number): Promise<FormVersionRecord | null>;
+    listVersionRecords(formId: string): Promise<readonly FormVersionRecord[]>;
+    commitVersionTransition(plan: VersionTransitionPlan): Promise<Result<{
+        readonly success: true;
+    }, StorageCommitError>>;
 }
 interface BaseQuestionAggregate {
     readonly fieldId: string;
@@ -442,9 +527,17 @@ interface SubmissionCursorValue {
     readonly submittedAt: string;
     readonly responseId: string;
 }
+interface TextAnswerCursorValue {
+    readonly responseId: string;
+    readonly fieldId: string;
+}
 declare function encodeSubmissionCursor(value: SubmissionCursorValue): string;
 declare function decodeSubmissionCursor(cursor: string): SubmissionCursorValue;
+declare function encodeTextAnswerCursor(value: TextAnswerCursorValue): string;
+declare function decodeTextAnswerCursor(cursor: string): TextAnswerCursorValue;
 declare function normalizeSubmissionPageSize(pageSize: number | undefined, fallback?: number): number;
+declare function jsonValuesEqual(left: JsonValue | undefined, right: JsonValue | undefined): boolean;
+declare function matchesSubmissionFilter(submission: FormSubmission, filter: SubmissionFilter): boolean;
 declare function matchesSubmissionPageFilters(submission: FormSubmission, options: Pick<SubmissionPageQueryOptions, "filter" | "metadataFilters">): boolean;
 
 interface CollectedLocales {
@@ -520,4 +613,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 CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnContext, type CsvColumnDef, type CsvExportOptions, type DeleteDraftOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type JsonValue, type LocalizedText, type MultiSelectField, type NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PopulateTranslationOptions, type PublishDraftOptions, type PublishDraftResult, type Question, type QuestionAggregate, type QuestionType, type RatingField, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type StreamCsvOptions, type SubmissionCursorValue, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionError, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeSubmissionCursor, deleteDraft, dispatchWebhook, encodeSubmissionCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, isDisplayConditionSatisfied, isQuestionVisible, matchesSubmissionPageFilters, normalizeSubmissionPageSize, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };
+export { type AccumulatorReport, type AccumulatorResponse, type AccumulatorSkipReason, type AnswerValidationResult, type AsyncTranslationAdapter, type BaseField, type CheckboxField, type CheckboxQuestionAggregate, type ChoiceDistributionEntry, type ChoiceOption, type ChoiceQuestionAggregate, type CloneVersionOptions, type CollectedLocales, type ConditionOperator, type ConditionValue, type CreateSubmissionOptions, type CrossTabulationResult, type CsvColumnContext, type CsvColumnDef, type CsvExportOptions, type DeleteDraftOptions, type DisplayCondition, type ExtensibleNode, type FieldOption, type FieldType, type FormAnalytics, type FormEvent, type FormEventType, type FormField, type FormPage, type FormPolicy, type FormResponse, type FormSchema, type FormStorageAdapter, type FormSubmission, type FormValue, type FormValues, type FormVersionRecord, type FormVersionState, type FormVersionStatus, type JsonValue, type LocalizedText, type MultiSelectField, type NodeWritableStream, type NumberField, type NumberQuestionAggregate, type NumericSummary, type OptionAggregate, type PagedSubmissionStorageAdapter, type PopulateTranslationOptions, type PublishDraftOptions, type PublishDraftResult, type Question, type QuestionAggregate, type QuestionType, type RatingField, type ResponseAccumulator, type ResponseAccumulatorOptions, type Result, type SchemaIssue, type SchemaStructureIssue, type SchemaStructureIssueType, type SchemaTranslations, type SchemaValidationResult, type SelectField, type StorageAdapter, type StorageCommitError, type StreamCsvOptions, type SubmissionCursorValue, type SubmissionFilter, type SubmissionPage, type SubmissionPageQueryOptions, type SubmissionQueryOptions, type TextAnswerCursorValue, type TextAnswerItem, type TextAnswerPage, type TextAnswerPageQueryOptions, type TextField, type TextQuestionAggregate, type TranslationAdapter, type TranslationReport, type TranslationSlot, type ValidateFormSchemaOptions, type ValidationCode, type ValidationError, type ValidationIssue, type VersionTransitionError, type VersionTransitionEvent, type VersionTransitionPlan, type VersionedFormStorageAdapter, type WebhookConfig, type WebhookDispatchResult, aggregateResponses, assertValidFormSchema, assertVersionMutable, calculateChoiceDistribution, calculateCrossTabulation, calculateFieldVisibility, calculateNumericSummary, calculatePageVisibility, cloneVersionToDraft, collectSchemaLocales, createCloneTransitionPlan, createDeleteDraftTransitionPlan, createPublishTransitionPlan, createResponseAccumulator, createSubmission, decodeSubmissionCursor, decodeTextAnswerCursor, deleteDraft, dispatchWebhook, encodeSubmissionCursor, encodeTextAnswerCursor, escapeCsvCell, exportResponsesToCsv, exportResponsesToCsvStream, isDisplayConditionSatisfied, isQuestionVisible, jsonValuesEqual, matchesSubmissionFilter, matchesSubmissionPageFilters, normalizeSubmissionPageSize, pipeResponsesToCsvStream, populateSchemaTranslations, publishDraft, resolveFormTranslation, resolveLocalizedSchema, sanitizeSchema, selectVisibleAnswers, transformFieldType, validateAnswers, validateFormSchema, validatePageAnswers, validateSchemaStructure };

package/dist/index.js

@@ -1504,6 +1504,24 @@ function decodeSubmissionCursor(cursor) {
     throw new TypeError("cursor must be a valid form-engine cursor.", { cause });
   }
 }
+function encodeTextAnswerCursor(value) {
+  if (value.responseId.length === 0 || value.fieldId.length === 0) {
+    throw new TypeError("Text answer cursor values must not be empty.");
+  }
+  return encodeBase64(new TextEncoder().encode(JSON.stringify(value)));
+}
+function decodeTextAnswerCursor(cursor) {
+  try {
+    const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(decodeBase64(cursor)));
+    if (typeof parsed !== "object" || parsed === null || !("responseId" in parsed) || typeof parsed.responseId !== "string" || parsed.responseId.length === 0 || !("fieldId" in parsed) || typeof parsed.fieldId !== "string" || parsed.fieldId.length === 0) {
+      throw new TypeError("text answer cursor payload is invalid.");
+    }
+    return { responseId: parsed.responseId, fieldId: parsed.fieldId };
+  } catch (cause) {
+    if (cause instanceof TypeError && cause.message === "text answer cursor payload is invalid.") throw cause;
+    throw new TypeError("cursor must be a valid text answer 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.");
@@ -1528,8 +1546,39 @@ function jsonValuesEqual(left, right) {
   const rightKeys = Object.keys(right);
   return leftKeys.length === rightKeys.length && leftKeys.every((key) => Object.hasOwn(right, key) && jsonValuesEqual(left[key], right[key]));
 }
+function readSubmissionPath(submission, path) {
+  if (path.length === 0 || path.split(".").some((part) => part.length === 0 || part === "__proto__" || part === "constructor")) {
+    return void 0;
+  }
+  let current = submission;
+  for (const part of path.split(".")) {
+    if (typeof current !== "object" || current === null || !Object.hasOwn(current, part)) return void 0;
+    current = current[part];
+  }
+  return current;
+}
+function compareRangeValue(value, boundary, direction) {
+  if (typeof value === "number" && typeof boundary === "number") {
+    return direction === "from" ? value >= boundary : value <= boundary;
+  }
+  if (typeof value === "string" && typeof boundary === "string") {
+    return direction === "from" ? value >= boundary : value <= boundary;
+  }
+  return false;
+}
+function matchesSubmissionFilter(submission, filter) {
+  if (filter.op === "and") return filter.filters.every((item) => matchesSubmissionFilter(submission, item));
+  if (filter.op === "or") return filter.filters.some((item) => matchesSubmissionFilter(submission, item));
+  const value = readSubmissionPath(submission, filter.path);
+  if (filter.op === "eq") return jsonValuesEqual(value, filter.value);
+  if (filter.op === "in") return filter.values.some((candidate) => jsonValuesEqual(value, candidate));
+  if (filter.op === "exists") return filter.value ? value !== void 0 : value === void 0;
+  return (filter.from === void 0 || compareRangeValue(value, filter.from, "from")) && (filter.to === void 0 || compareRangeValue(value, filter.to, "to"));
+}
 function matchesSubmissionPageFilters(submission, options) {
-  if (options.filter !== void 0 && !options.filter(submission)) return false;
+  if (options.filter !== void 0 && !(typeof options.filter === "function" ? options.filter(submission) : matchesSubmissionFilter(submission, options.filter))) {
+    return false;
+  }
   if (options.metadataFilters === void 0) return true;
   return Object.entries(options.metadataFilters).every(
     ([key, value]) => jsonValuesEqual(submission.metadata?.[key], value)
@@ -1988,6 +2037,21 @@ function validateState(state) {
     throw new TypeError("revision must be a non-negative safe integer.");
   }
 }
+function requireTimestamp(value, name) {
+  const timestamp = value ?? "1970-01-01T00:00:00.000Z";
+  if (!Number.isFinite(Date.parse(timestamp))) throw new TypeError(`${name} must be a valid date string.`);
+  return timestamp;
+}
+function transitionEvent(type, state, nextState, affectedVersions, occurredAt) {
+  return {
+    type,
+    formId: state.formId,
+    fromRevision: state.revision,
+    toRevision: nextState.revision,
+    affectedVersions,
+    occurredAt
+  };
+}
 function cloneVersionToDraft(state, sourceSchema, options = {}) {
   validateState(state);
   if (sourceSchema.id !== state.formId) throw new TypeError("sourceSchema.id must match state.formId.");
@@ -2031,16 +2095,61 @@ function cloneVersionToDraft(state, sourceSchema, options = {}) {
     }
   };
 }
+function createCloneTransitionPlan(state, sourceRecord, options = {}) {
+  if (sourceRecord.formId !== state.formId || sourceRecord.schema.id !== sourceRecord.formId || sourceRecord.schema.version !== sourceRecord.version || sourceRecord.status !== "published" && !options.allowedSourceVersions?.includes(sourceRecord.version)) {
+    return {
+      success: false,
+      error: {
+        type: "invalid_source_version",
+        requestedVersion: sourceRecord.version,
+        ...state.publishedVersion === void 0 ? {} : { publishedVersion: state.publishedVersion }
+      }
+    };
+  }
+  const result = cloneVersionToDraft(state, sourceRecord.schema, options);
+  if (!result.success) return result;
+  const timestamp = requireTimestamp(options.clonedAt, "clonedAt");
+  const draftRecord = {
+    formId: state.formId,
+    version: result.value.draftSchema.version,
+    status: "draft",
+    schema: result.value.draftSchema,
+    revision: 1,
+    createdFromVersion: sourceRecord.version,
+    createdAt: timestamp,
+    ...options.metadata === void 0 ? {} : { metadata: options.metadata }
+  };
+  return {
+    success: true,
+    value: {
+      nextState: result.value.nextState,
+      plan: {
+        formId: state.formId,
+        expectedRevision: options.expectedRevision ?? state.revision,
+        nextRevision: result.value.nextState.revision,
+        draftToCreate: draftRecord,
+        events: [transitionEvent("draft.created", state, result.value.nextState, [draftRecord.version], timestamp)],
+        nextVersion: result.value.nextState.nextVersion,
+        timestamp
+      }
+    }
+  };
+}
 function validatePublishedRecord(state, record) {
-  if (record === void 0) return;
-  if (record.formId !== state.formId || record.version !== state.publishedVersion || record.status !== "published" || record.schema.id !== record.formId || record.schema.version !== record.version) {
+  if (state.publishedVersion !== void 0 && record?.version !== state.publishedVersion) {
+    return {
+      success: false,
+      error: { type: "missing_published_record", expectedVersion: state.publishedVersion }
+    };
+  }
+  if (record === void 0) return void 0;
+  if (record.formId !== state.formId || record.status !== "published" || record.schema.id !== record.formId || record.schema.version !== record.version) {
     throw new TypeError("currentPublishedRecord must match the state's published version.");
   }
+  return void 0;
 }
 function transitionTimestamp(options) {
-  const timestamp = options.publishedAt ?? options.timestamp ?? "1970-01-01T00:00:00.000Z";
-  if (!Number.isFinite(Date.parse(timestamp))) throw new TypeError("publishedAt must be a valid date string.");
-  return timestamp;
+  return requireTimestamp(options.publishedAt ?? options.timestamp, "publishedAt");
 }
 async function publishDraft(state, draftSchema, options = {}) {
   validateState(state);
@@ -2049,7 +2158,8 @@ async function publishDraft(state, draftSchema, options = {}) {
   if (state.draftVersion === void 0 || draftSchema.id !== state.formId || draftSchema.version !== state.draftVersion) {
     return { success: false, error: { type: "draft_not_found" } };
   }
-  validatePublishedRecord(state, options.currentPublishedRecord);
+  const publishedRecordError = validatePublishedRecord(state, options.currentPublishedRecord);
+  if (publishedRecordError !== void 0) return publishedRecordError;
   const validation = await options.validate?.(draftSchema);
   if (validation === false || Array.isArray(validation) && validation.length > 0) {
     return {
@@ -2123,6 +2233,19 @@ async function createPublishTransitionPlan(state, draftRecord, options = {}) {
         draftToDeleteVersion: draftRecord.version,
         publishedRecordToSave,
         archivedRecordsToSave: result.value.archivedRecords,
+        events: [
+          ...result.value.archivedRecords.length === 0 ? [] : [
+            transitionEvent(
+              "version.archived",
+              state,
+              result.value.nextState,
+              result.value.archivedRecords.map((record) => record.version),
+              timestamp
+            )
+          ],
+          transitionEvent("version.published", state, result.value.nextState, [draftRecord.version], timestamp)
+        ],
+        nextVersion: result.value.nextState.nextVersion,
         timestamp
       }
     }
@@ -2139,6 +2262,29 @@ function deleteDraft(state, options = {}) {
     value: { nextState: { ...stateWithoutDraft, revision: state.revision + 1 } }
   };
 }
+function createDeleteDraftTransitionPlan(state, draftRecord, options = {}) {
+  if (draftRecord.formId !== state.formId || draftRecord.version !== state.draftVersion || draftRecord.status !== "draft" || draftRecord.schema.id !== state.formId || draftRecord.schema.version !== draftRecord.version) {
+    return { success: false, error: { type: "draft_not_found" } };
+  }
+  const result = deleteDraft(state, options);
+  if (!result.success) return result;
+  const timestamp = requireTimestamp(options.deletedAt, "deletedAt");
+  return {
+    success: true,
+    value: {
+      nextState: result.value.nextState,
+      plan: {
+        formId: state.formId,
+        expectedRevision: options.expectedRevision ?? state.revision,
+        nextRevision: result.value.nextState.revision,
+        draftToDeleteVersion: draftRecord.version,
+        events: [transitionEvent("draft.deleted", state, result.value.nextState, [draftRecord.version], timestamp)],
+        nextVersion: result.value.nextState.nextVersion,
+        timestamp
+      }
+    }
+  };
+}
 function assertVersionMutable(status) {
   if (status !== "draft") {
     const error = { type: "version_immutable", status };
@@ -2156,18 +2302,24 @@ export {
   calculatePageVisibility,
   cloneVersionToDraft,
   collectSchemaLocales,
+  createCloneTransitionPlan,
+  createDeleteDraftTransitionPlan,
   createPublishTransitionPlan,
   createResponseAccumulator,
   createSubmission,
   decodeSubmissionCursor,
+  decodeTextAnswerCursor,
   deleteDraft,
   dispatchWebhook,
   encodeSubmissionCursor,
+  encodeTextAnswerCursor,
   escapeCsvCell,
   exportResponsesToCsv,
   exportResponsesToCsvStream,
   isDisplayConditionSatisfied,
   isQuestionVisible,
+  jsonValuesEqual,
+  matchesSubmissionFilter,
   matchesSubmissionPageFilters,
   normalizeSubmissionPageSize,
   pipeResponsesToCsvStream,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/core",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "publishConfig": {
     "access": "public"
   },