From 2ab5934778ff18b858dc16cf31848f16d9b09a22 Mon Sep 17 00:00:00 2001
From: eyelidlessness <gnosis@gmail.com>
Date: Wed, 26 Feb 2025 09:55:53 -0800
Subject: [PATCH 1/8] Remove incorrect `submissionDefinition` detritus
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Without doing some commit history archaeology I’m not sure how this ended up here, but it’s wrong (`ClientReactiveSubmittableInstance` doesn’t specify this getter). In any case, I confirmed nothing references this before removing it!

(Also removes redundant `// RootNode` header)
---
 packages/xforms-engine/src/instance/Root.ts | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/packages/xforms-engine/src/instance/Root.ts b/packages/xforms-engine/src/instance/Root.ts
index 3c371c3d..c971a6fe 100644
--- a/packages/xforms-engine/src/instance/Root.ts
+++ b/packages/xforms-engine/src/instance/Root.ts
@@ -3,7 +3,6 @@ import type { Accessor } from 'solid-js';
 import type { ActiveLanguage, FormLanguage, FormLanguages } from '../client/FormLanguage.ts';
 import type { FormNodeID } from '../client/identity.ts';
 import type { RootNode } from '../client/RootNode.ts';
-import type { SubmissionDefinition } from '../client/submission/SubmissionDefinition.ts';
 import type {
 	SubmissionChunkedType,
 	SubmissionOptions,
@@ -81,13 +80,6 @@ export class Root
 	readonly currentState: MaterializedChildren<CurrentState<RootStateSpec>, GeneralChildNode>;
 	readonly validationState: AncestorNodeValidationState;
 	readonly submissionState: SubmissionState;
-
-	// ClientReactiveSubmittableInstance
-	get submissionDefinition(): SubmissionDefinition {
-		return this.definition.submission;
-	}
-
-	// RootNode
 	readonly languages: FormLanguages;
 
 	constructor(parent: PrimaryInstance) {

From 99f0869f9349de7ff8c4d1858d3d78a56e49bf0f Mon Sep 17 00:00:00 2001
From: eyelidlessness <gnosis@gmail.com>
Date: Wed, 26 Feb 2025 12:48:48 -0800
Subject: [PATCH 2/8] engine (typo): Prepeare* -> Prepare*

---
 .../src/lib/client-reactivity/submission/prepareSubmission.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/xforms-engine/src/lib/client-reactivity/submission/prepareSubmission.ts b/packages/xforms-engine/src/lib/client-reactivity/submission/prepareSubmission.ts
index 6a72075f..3bc85802 100644
--- a/packages/xforms-engine/src/lib/client-reactivity/submission/prepareSubmission.ts
+++ b/packages/xforms-engine/src/lib/client-reactivity/submission/prepareSubmission.ts
@@ -134,14 +134,14 @@ const chunkedSubmissionResult = (
 	};
 };
 
-export interface PrepeareSubmissionOptions<ChunkedType extends SubmissionChunkedType> {
+export interface PrepareSubmissionOptions<ChunkedType extends SubmissionChunkedType> {
 	readonly chunked: ChunkedType;
 	readonly maxSize: number;
 }
 
 export const prepareSubmission = <ChunkedType extends SubmissionChunkedType>(
 	instanceRoot: ClientReactiveSubmittableInstance,
-	options: PrepeareSubmissionOptions<ChunkedType>
+	options: PrepareSubmissionOptions<ChunkedType>
 ): SubmissionResult<ChunkedType> => {
 	const validation = validateSubmission(instanceRoot);
 	const definition = instanceRoot.definition.submission;

From f94d665c722904f764592ed09c1596d8cf2ddd6f Mon Sep 17 00:00:00 2001
From: eyelidlessness <gnosis@gmail.com>
Date: Wed, 26 Feb 2025 12:45:20 -0800
Subject: [PATCH 3/8] =?UTF-8?q?engine=20(client):=20=E2=80=9Csubmission?=
 =?UTF-8?q?=E2=80=9D-specific=20terminology=20to=20=E2=80=9Cinstance?=
 =?UTF-8?q?=E2=80=9D=20as=20appropriate?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This is being condensed into a single commit to create less git history noise. Each checklist item is being added below, as each corresponding change is appended.

- [x] `SubmissionChunkedType` (enumerated type) -> `InstancePayloadType`
- [x] `ChunkedType` (commonly used type parameter for ^) -> `PayloadType`
- [x] `chunked` (options property) -> `payloadType`
- [x] `SubmissionOptions` (interface union) & related base interfaces -> `InstancePayloadOptions`
    - [x] `SubmissionOptions.ts` -> `InstancePayloadOptions.ts`
- [x] Constants:
    - `SUBMISSION_INSTANCE_FILE_NAME` & `SubmissionInstanceFileName` -> `INSTANCE_FILE_NAME`
    - `SUBMISSION_INSTANCE_FILE_TYPE` & `SubmissionInstanceFileType` -> `INSTANCE_FILE_TYPE`
- [x] `SubmissionInstanceFile` -> `InstanceFile`
- [x] `SubmissionData` -> `InstanceData`
- [x] `SubmissionState.submissionXML` -> `SubmissionState.instanceXML`
- [x] `SubmissionState` (interface) -> `InstanceState`
- [x] `submissionState` -> `instanceState`, where property of:
    - `BaseNode` (client interface) and any more specific subtype thereof
    - `ClientReactiveSubmittable*`
- [x] (See `@todo` JSDoc comments) Note consideration of moving `instanceValue` state into `InstanceState`
- [x] `SubmissionResult` (type) & related -> `InstancePayload` etc (same naming conventions)
- [x] `client/submission/Instance*` -> `client/serialization/Instance*`
- [x] `RootNode.prepareSubmission` -> `RootNode.prepareInstancePayload`
---
 .../src/assertion/extensions/submission.ts    |  87 ++++++------
 packages/scenario/src/jr/Scenario.ts          |   6 +-
 .../web-forms/src/components/OdkWebForm.vue   |  16 +--
 packages/web-forms/src/demo/FormPreview.vue   |   8 +-
 packages/xforms-engine/src/client/BaseNode.ts |   8 +-
 .../xforms-engine/src/client/BaseValueNode.ts |  10 +-
 packages/xforms-engine/src/client/RootNode.ts |  46 ++++---
 .../xforms-engine/src/client/constants.ts     |   8 +-
 .../src/client/serialization/InstanceData.ts  |   9 ++
 .../src/client/serialization/InstanceFile.ts  |   9 ++
 .../client/serialization/InstancePayload.ts   | 124 ++++++++++++++++++
 .../serialization/InstancePayloadOptions.ts   |  28 ++++
 .../src/client/serialization/InstanceState.ts |  14 ++
 .../src/client/submission/SubmissionData.ts   |  12 --
 .../submission/SubmissionInstanceFile.ts      |   9 --
 .../client/submission/SubmissionOptions.ts    |  28 ----
 .../src/client/submission/SubmissionResult.ts | 124 ------------------
 .../src/client/submission/SubmissionState.ts  |  14 --
 packages/xforms-engine/src/index.ts           |  12 +-
 packages/xforms-engine/src/instance/Group.ts  |   6 +-
 .../src/instance/PrimaryInstance.ts           |  24 ++--
 packages/xforms-engine/src/instance/Root.ts   |  22 ++--
 .../xforms-engine/src/instance/Subtree.ts     |   6 +-
 .../src/instance/abstract/InstanceNode.ts     |   4 +-
 .../instance/abstract/UnsupportedControl.ts   |   6 +-
 .../src/instance/abstract/ValueNode.ts        |   6 +-
 .../ClientReactiveSubmittableLeafNode.ts      |  14 +-
 .../ClientReactiveSubmittableParentNode.ts    |   6 +-
 .../ClientReactiveSubmittableValueNode.ts     |   8 +-
 .../src/instance/repeat/BaseRepeatRange.ts    |   6 +-
 .../src/instance/repeat/RepeatInstance.ts     |   6 +-
 .../createInstanceSubmissionState.ts          |   8 +-
 .../createLeafNodeSubmissionState.ts          |   6 +-
 .../createNodeRangeSubmissionState.ts         |   8 +-
 .../createParentNodeSubmissionState.ts        |   8 +-
 .../submission/createRootSubmissionState.ts   |   8 +-
 .../createValueNodeSubmissionState.ts         |   6 +-
 .../submission/prepareSubmission.ts           |  79 ++++++-----
 38 files changed, 408 insertions(+), 401 deletions(-)
 create mode 100644 packages/xforms-engine/src/client/serialization/InstanceData.ts
 create mode 100644 packages/xforms-engine/src/client/serialization/InstanceFile.ts
 create mode 100644 packages/xforms-engine/src/client/serialization/InstancePayload.ts
 create mode 100644 packages/xforms-engine/src/client/serialization/InstancePayloadOptions.ts
 create mode 100644 packages/xforms-engine/src/client/serialization/InstanceState.ts
 delete mode 100644 packages/xforms-engine/src/client/submission/SubmissionData.ts
 delete mode 100644 packages/xforms-engine/src/client/submission/SubmissionInstanceFile.ts
 delete mode 100644 packages/xforms-engine/src/client/submission/SubmissionOptions.ts
 delete mode 100644 packages/xforms-engine/src/client/submission/SubmissionResult.ts
 delete mode 100644 packages/xforms-engine/src/client/submission/SubmissionState.ts

diff --git a/packages/scenario/src/assertion/extensions/submission.ts b/packages/scenario/src/assertion/extensions/submission.ts
index 866a06dd..62a854e6 100644
--- a/packages/scenario/src/assertion/extensions/submission.ts
+++ b/packages/scenario/src/assertion/extensions/submission.ts
@@ -12,10 +12,10 @@ import {
 import type { SimpleAssertionResult } from '@getodk/common/test/assertions/vitest/shared-extension-types.ts';
 import type { AssertIs } from '@getodk/common/types/assertions/AssertIs.ts';
 import type {
-	SubmissionChunkedType,
-	SubmissionData,
-	SubmissionInstanceFile,
-	SubmissionResult,
+	InstanceData,
+	InstanceFile,
+	InstancePayload,
+	InstancePayloadType,
 } from '@getodk/xforms-engine';
 import { constants } from '@getodk/xforms-engine';
 import { assert, expect } from 'vitest';
@@ -38,10 +38,10 @@ const compareSubmissionXML = (actual: string, expected: string): SimpleAssertion
 
 const assertFormData: AssertIs<FormData> = instanceAssertion(FormData);
 
-type AnySubmissionResult = SubmissionResult<SubmissionChunkedType>;
+type AnyInstancePayload = InstancePayload<InstancePayloadType>;
 
 /**
- * Validating the full {@link SubmissionResult} type is fairly involved. We
+ * Validating the full {@link InstancePayload} type is fairly involved. We
  * check the basic object shape (expected keys present, gut check a few easy to
  * check property types), on the assumption that downstream assertions will fail
  * if the runtime and static types disagree.
@@ -50,7 +50,7 @@ type AnySubmissionResult = SubmissionResult<SubmissionChunkedType>;
  * more complete validation here, serving as a smoke test for all tests
  * exercising aspects of a prepared submission result.
  */
-const assertSubmissionResult: AssertIs<AnySubmissionResult> = (value) => {
+const assertInstancePayload: AssertIs<AnyInstancePayload> = (value) => {
 	assertUnknownObject(value);
 	assertString(value.status);
 	if (value.violations !== null) {
@@ -69,30 +69,30 @@ const assertSubmissionResult: AssertIs<AnySubmissionResult> = (value) => {
 
 const assertFile: AssertIs<File> = instanceAssertion(File);
 
-const { SUBMISSION_INSTANCE_FILE_NAME, SUBMISSION_INSTANCE_FILE_TYPE } = constants;
+const { INSTANCE_FILE_NAME, INSTANCE_FILE_TYPE } = constants;
 
-const assertSubmissionInstanceFile: AssertIs<SubmissionInstanceFile> = (value) => {
+const assertInstanceFile: AssertIs<InstanceFile> = (value) => {
 	assertFile(value);
 
-	if (value.name !== SUBMISSION_INSTANCE_FILE_NAME) {
-		throw new Error(`Expected file named ${SUBMISSION_INSTANCE_FILE_NAME}, got ${value.name}`);
+	if (value.name !== INSTANCE_FILE_NAME) {
+		throw new Error(`Expected file named ${INSTANCE_FILE_NAME}, got ${value.name}`);
 	}
 
-	if (value.type !== SUBMISSION_INSTANCE_FILE_TYPE) {
-		throw new Error(`Expected file of type ${SUBMISSION_INSTANCE_FILE_TYPE}, got ${value.type}`);
+	if (value.type !== INSTANCE_FILE_TYPE) {
+		throw new Error(`Expected file of type ${INSTANCE_FILE_TYPE}, got ${value.type}`);
 	}
 };
 
-type ChunkedSubmissionData = readonly [SubmissionData, ...SubmissionData[]];
+type ChunkedInstanceData = readonly [InstanceData, ...InstanceData[]];
 
 const isChunkedSubmissionData = (
-	data: ChunkedSubmissionData | SubmissionData
-): data is ChunkedSubmissionData => {
+	data: ChunkedInstanceData | InstanceData
+): data is ChunkedInstanceData => {
 	return Array.isArray(data);
 };
 
-const getSubmissionData = (submissionResult: AnySubmissionResult): SubmissionData => {
-	const { data } = submissionResult;
+const getInstanceData = (payload: AnyInstancePayload): InstanceData => {
+	const { data } = payload;
 
 	if (isChunkedSubmissionData(data)) {
 		const [first] = data;
@@ -103,13 +103,11 @@ const getSubmissionData = (submissionResult: AnySubmissionResult): SubmissionDat
 	return data;
 };
 
-const getSubmissionInstanceFile = (
-	submissionResult: AnySubmissionResult
-): SubmissionInstanceFile => {
-	const submissionData = getSubmissionData(submissionResult);
-	const file = submissionData.get(SUBMISSION_INSTANCE_FILE_NAME);
+const getInstanceFile = (payload: AnyInstancePayload): InstanceFile => {
+	const instanceData = getInstanceData(payload);
+	const file = instanceData.get(INSTANCE_FILE_NAME);
 
-	assertSubmissionInstanceFile(file);
+	assertInstanceFile(file);
 
 	return file;
 };
@@ -125,30 +123,27 @@ export const submissionExtensions = extendExpect(expect, {
 		}
 	),
 
-	toBeReadyForSubmission: new ArbitraryConditionExpectExtension(
-		assertSubmissionResult,
-		(result) => {
-			try {
-				expect(result).toMatchObject({
-					status: 'ready',
-					violations: null,
-				});
-
-				return true;
-			} catch (error) {
-				if (error instanceof Error) {
-					return error;
-				}
-
-				// eslint-disable-next-line no-console
-				console.error(error);
-				return new Error('Unknown error');
+	toBeReadyForSubmission: new ArbitraryConditionExpectExtension(assertInstancePayload, (result) => {
+		try {
+			expect(result).toMatchObject({
+				status: 'ready',
+				violations: null,
+			});
+
+			return true;
+		} catch (error) {
+			if (error instanceof Error) {
+				return error;
 			}
+
+			// eslint-disable-next-line no-console
+			console.error(error);
+			return new Error('Unknown error');
 		}
-	),
+	}),
 
 	toBePendingSubmissionWithViolations: new ArbitraryConditionExpectExtension(
-		assertSubmissionResult,
+		assertInstancePayload,
 		(result) => {
 			try {
 				expect(result.status).toBe('pending');
@@ -173,10 +168,10 @@ export const submissionExtensions = extendExpect(expect, {
 	),
 
 	toHavePreparedSubmissionXML: new AsyncAsymmetricTypedExpectExtension(
-		assertSubmissionResult,
+		assertInstancePayload,
 		assertString,
 		async (actual, expected): Promise<SimpleAssertionResult> => {
-			const instanceFile = getSubmissionInstanceFile(actual);
+			const instanceFile = getInstanceFile(actual);
 			const actualText = await getBlobText(instanceFile);
 
 			return compareSubmissionXML(actualText, expected);
diff --git a/packages/scenario/src/jr/Scenario.ts b/packages/scenario/src/jr/Scenario.ts
index 4632c71c..003e3d21 100644
--- a/packages/scenario/src/jr/Scenario.ts
+++ b/packages/scenario/src/jr/Scenario.ts
@@ -12,8 +12,8 @@ import { constants as ENGINE_CONSTANTS } from '@getodk/xforms-engine';
 import type { Accessor, Setter } from 'solid-js';
 import { createMemo, createSignal, runWithOwner } from 'solid-js';
 import { afterEach, assert, expect } from 'vitest';
-import { SelectValuesAnswer } from '../answer/SelectValuesAnswer.ts';
 import { RankValuesAnswer } from '../answer/RankValuesAnswer.ts';
+import { SelectValuesAnswer } from '../answer/SelectValuesAnswer.ts';
 import type { ValueNodeAnswer } from '../answer/ValueNodeAnswer.ts';
 import { answerOf } from '../client/answerOf.ts';
 import type { InitializeTestFormOptions, TestFormResource } from '../client/init.ts';
@@ -964,7 +964,7 @@ export class Scenario {
 	}
 
 	proposed_serializeInstance(): string {
-		return this.instanceRoot.submissionState.submissionXML;
+		return this.instanceRoot.instanceState.instanceXML;
 	}
 
 	/**
@@ -975,7 +975,7 @@ export class Scenario {
 	 * already handled by {@link proposed_serializeInstance}).
 	 */
 	prepareWebFormsSubmission() {
-		return this.instanceRoot.prepareSubmission();
+		return this.instanceRoot.prepareInstancePayload();
 	}
 
 	// TODO: consider adapting tests which use the following interfaces to use
diff --git a/packages/web-forms/src/components/OdkWebForm.vue b/packages/web-forms/src/components/OdkWebForm.vue
index e06d01d2..feed0376 100644
--- a/packages/web-forms/src/components/OdkWebForm.vue
+++ b/packages/web-forms/src/components/OdkWebForm.vue
@@ -1,8 +1,8 @@
 <script setup lang="ts">
 import type {
-	ChunkedSubmissionResult,
+	ChunkedInstancePayload,
 	MissingResourceBehavior,
-	MonolithicSubmissionResult,
+	MonolithicInstancePayload,
 } from '@getodk/xforms-engine';
 import { initializeForm, type FetchFormAttachment, type RootNode } from '@getodk/xforms-engine';
 import Button from 'primevue/button';
@@ -33,8 +33,8 @@ const props = defineProps<OdkWebFormsProps>();
 
 // eslint-disable-next-line @typescript-eslint/consistent-type-definitions -- evidently a type must be used for this to be assigned to a name (which we use!); as an interface, it won't satisfy the `Record` constraint of `defineEmits`.
 type OdkWebFormEmits = {
-	submit: [submissionPayload: MonolithicSubmissionResult];
-	submitChunked: [submissionPayload: ChunkedSubmissionResult];
+	submit: [submissionPayload: MonolithicInstancePayload];
+	submitChunked: [submissionPayload: ChunkedInstancePayload];
 };
 
 /**
@@ -76,8 +76,8 @@ const isEmitSubscribed = (eventKey: EventKey): boolean => {
 
 const emitSubmit = async (root: RootNode) => {
 	if (isEmitSubscribed('onSubmit')) {
-		const payload = await root.prepareSubmission({
-			chunked: 'monolithic',
+		const payload = await root.prepareInstancePayload({
+			payloadType: 'monolithic',
 		});
 
 		emit('submit', payload);
@@ -92,8 +92,8 @@ const emitSubmitChunked = async (root: RootNode) => {
 			throw new Error('The `submissionMaxSize` prop is required for chunked submissions');
 		}
 
-		const payload = await root.prepareSubmission({
-			chunked: 'chunked',
+		const payload = await root.prepareInstancePayload({
+			payloadType: 'chunked',
 			maxSize,
 		});
 
diff --git a/packages/web-forms/src/demo/FormPreview.vue b/packages/web-forms/src/demo/FormPreview.vue
index 3140614b..ed9b3764 100644
--- a/packages/web-forms/src/demo/FormPreview.vue
+++ b/packages/web-forms/src/demo/FormPreview.vue
@@ -1,10 +1,10 @@
 <script setup lang="ts">
 import { xformFixturesByCategory, XFormResource } from '@getodk/common/fixtures/xforms.ts';
 import type {
-	ChunkedSubmissionResult,
+	ChunkedInstancePayload,
 	FetchFormAttachment,
 	MissingResourceBehavior,
-	MonolithicSubmissionResult,
+	MonolithicInstancePayload,
 } from '@getodk/xforms-engine';
 import { constants as ENGINE_CONSTANTS } from '@getodk/xforms-engine';
 import { ref } from 'vue';
@@ -55,14 +55,14 @@ xformResource
 		alert('Failed to load the Form XML');
 	});
 
-const handleSubmit = (payload: MonolithicSubmissionResult) => {
+const handleSubmit = (payload: MonolithicInstancePayload) => {
 	// eslint-disable-next-line no-console
 	console.log('submission payload:', payload);
 
 	alert(`Submit button was pressed`);
 };
 
-const handleSubmitChunked = (payload: ChunkedSubmissionResult) => {
+const handleSubmitChunked = (payload: ChunkedInstancePayload) => {
 	// eslint-disable-next-line no-console
 	console.log('CHUNKED submission payload:', payload);
 };
diff --git a/packages/xforms-engine/src/client/BaseNode.ts b/packages/xforms-engine/src/client/BaseNode.ts
index 21433352..566f8a3a 100644
--- a/packages/xforms-engine/src/client/BaseNode.ts
+++ b/packages/xforms-engine/src/client/BaseNode.ts
@@ -5,7 +5,7 @@ import type { OpaqueReactiveObjectFactory } from './OpaqueReactiveObjectFactory.
 import type { TextRange } from './TextRange.ts';
 import type { FormNodeID } from './identity.ts';
 import type { InstanceNodeType } from './node-types.ts';
-import type { SubmissionState } from './submission/SubmissionState.ts';
+import type { InstanceState } from './serialization/InstanceState.ts';
 import type {
 	AncestorNodeValidationState,
 	LeafNodeValidationState,
@@ -256,14 +256,14 @@ export interface BaseNode {
 	readonly validationState: NodeValidationState;
 
 	/**
-	 * Represents the current submission state of the node.
+	 * Represents the current instance state of the node.
 	 *
-	 * @see {@link SubmissionState.submissionXML} for additional detail.
+	 * @see {@link InstanceState.instanceXML} for additional detail.
 	 *
 	 * @todo Consider whether this can (should) be merged with
 	 * {@link currentState}, while providing the same client-reactivity
 	 * guarantees. (The challenge there is in defining client-reactive state which
 	 * self-referentially derives state from its own definition.)
 	 */
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 }
diff --git a/packages/xforms-engine/src/client/BaseValueNode.ts b/packages/xforms-engine/src/client/BaseValueNode.ts
index 78e28147..6a2ab6df 100644
--- a/packages/xforms-engine/src/client/BaseValueNode.ts
+++ b/packages/xforms-engine/src/client/BaseValueNode.ts
@@ -2,6 +2,7 @@ import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
 import type { BaseNode, BaseNodeState } from './BaseNode.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { LeafNodeType } from './node-types.ts';
+import type { InstanceState } from './serialization/InstanceState.ts';
 import type { LeafNodeValidationState } from './validation.ts';
 import type { ValueType } from './ValueType.ts';
 
@@ -15,12 +16,14 @@ export interface BaseValueNodeState<Value> extends BaseNodeState {
 	 * {@link value} state. This representation allows access to the node's value
 	 * _as primary instance state_. In other words, this is the value which:
 	 *
-	 * - would be serialized as a text node in
-	 *   {@link SubmissionState.submissionXML} (note: this value is **NOT**
-	 *   escaped for XML serialization, as it is there)
+	 * - would be serialized as a text node in {@link InstanceState.instanceXML}
+	 *   (note: this value is **NOT** escaped for XML serialization, as it is
+	 *   there)
 	 *
 	 * - is used when the node's value is referenced in any of a form's XPath
 	 *   expressions
+	 *
+	 * @todo Consider moving into {@link InstanceState}
 	 */
 	get instanceValue(): string;
 }
@@ -32,4 +35,5 @@ export interface BaseValueNode<V extends ValueType = ValueType, Value = string>
 	readonly parent: GeneralParentNode;
 	readonly currentState: BaseValueNodeState<Value>;
 	readonly validationState: LeafNodeValidationState;
+	readonly instanceState: InstanceState;
 }
diff --git a/packages/xforms-engine/src/client/RootNode.ts b/packages/xforms-engine/src/client/RootNode.ts
index b5486d36..45fb31b4 100644
--- a/packages/xforms-engine/src/client/RootNode.ts
+++ b/packages/xforms-engine/src/client/RootNode.ts
@@ -3,12 +3,12 @@ import type { RootDefinition } from '../parse/model/RootDefinition.ts';
 import type { BaseNode, BaseNodeState } from './BaseNode.ts';
 import type { ActiveLanguage, FormLanguage, FormLanguages } from './FormLanguage.ts';
 import type { GeneralChildNode } from './hierarchy.ts';
-import type { SubmissionOptions } from './submission/SubmissionOptions.ts';
 import type {
-	ChunkedSubmissionResult,
-	MonolithicSubmissionResult,
-	SubmissionResult,
-} from './submission/SubmissionResult.ts';
+	ChunkedInstancePayload,
+	InstancePayload,
+	MonolithicInstancePayload,
+} from './serialization/InstancePayload.ts';
+import type { InstancePayloadOptions } from './serialization/InstancePayloadOptions.ts';
 import type { AncestorNodeValidationState } from './validation.ts';
 
 export interface RootNodeState extends BaseNodeState {
@@ -64,33 +64,41 @@ export interface RootNode extends BaseNode {
 	setLanguage(language: FormLanguage): RootNode;
 
 	/**
-	 * Prepares the current form instance state for submission.
+	 * Prepares the current form instance state as an {@link InstancePayload}.
 	 *
-	 * A {@link SubmissionResult} will be prepared even if the current form state
-	 * includes `constraint` or `required` violations. This is intended to serve
-	 * two purposes:
+	 * A payload will be prepared even if the current form state includes
+	 * `constraint` or `required` violations. This supports serveral purposes:
 	 *
-	 * - A client may effectively use this method as a part of its own "submit"
-	 *   routine, and use any violations included in the {@link SubmissionResult}
+	 * - A client may effectively use this method as a part of its "submit"
+	 *   workflow, and use any violations included in the {@link InstancePayload}
 	 *   to prompt users to address those violations.
 	 *
-	 * - A client may inspect the submission state of a form at any time.
+	 * - A client may inspect the serialized instance state of a form at any time.
 	 *   Depending on the client and use case, this may be a convenience (e.g. for
 	 *   developers to inspect that form state at a current point in time); or it
 	 *   may provide necessary functionality (e.g. for test or tooling clients).
 	 *
-	 * Note on asynchrony: preparing a {@link SubmissionResult} is expected to be
-	 * a fast operation. It may even be nearly instantaneous, or roughly
+	 * - A client may capture _incomplete_ instance state (e.g. for storage in
+	 *   client-side storage or similar persistance layer), to resume filling the
+	 *   instance at a later time.
+	 *
+	 * Note on asynchrony: preparing a {@link InstancePayload} is expected to be a
+	 * fast operation. It may even be nearly instantaneous, or roughly
 	 * proportionate to the size of the form itself. However, this method is
 	 * designed to be asynchronous out of an abundance of caution, anticipating
 	 * that some as-yet undeveloped operations on binary data (e.g. form
 	 * attachments) may themselves impose asynchrony (i.e. by interfaces provided
 	 * by the platform and/or external dependencies).
 	 *
-	 * A client may specify {@link SubmissionOptions<'chunked'>}, in which case a
-	 * {@link SubmissionResult<'chunked'>} will be produced, with form attachments
+	 * A client may specify {@link InstancePayloadOptions<'chunked'>}, in which
+	 * case a {@link ChunkedInstancePayload} will be produced, with form
+	 * attachments
 	 */
-	prepareSubmission(): Promise<MonolithicSubmissionResult>;
-	prepareSubmission(options: SubmissionOptions<'monolithic'>): Promise<MonolithicSubmissionResult>;
-	prepareSubmission(options: SubmissionOptions<'chunked'>): Promise<ChunkedSubmissionResult>;
+	prepareInstancePayload(): Promise<MonolithicInstancePayload>;
+	prepareInstancePayload(
+		options: InstancePayloadOptions<'monolithic'>
+	): Promise<MonolithicInstancePayload>;
+	prepareInstancePayload(
+		options: InstancePayloadOptions<'chunked'>
+	): Promise<ChunkedInstancePayload>;
 }
diff --git a/packages/xforms-engine/src/client/constants.ts b/packages/xforms-engine/src/client/constants.ts
index 67645445..c21ca8b1 100644
--- a/packages/xforms-engine/src/client/constants.ts
+++ b/packages/xforms-engine/src/client/constants.ts
@@ -70,8 +70,8 @@ type ValidationTextDefaults = typeof VALIDATION_TEXT;
 
 export type ValidationTextDefault<Role extends ValidationTextRole> = ValidationTextDefaults[Role];
 
-export const SUBMISSION_INSTANCE_FILE_NAME = 'xml_submission_file';
-export type SubmissionInstanceFileName = typeof SUBMISSION_INSTANCE_FILE_NAME;
+export const INSTANCE_FILE_NAME = 'xml_submission_file';
+export type INSTANCE_FILE_NAME = typeof INSTANCE_FILE_NAME;
 
-export const SUBMISSION_INSTANCE_FILE_TYPE = 'text/xml';
-export type SubmissionInstanceFileType = typeof SUBMISSION_INSTANCE_FILE_TYPE;
+export const INSTANCE_FILE_TYPE = 'text/xml';
+export type INSTANCE_FILE_TYPE = typeof INSTANCE_FILE_TYPE;
diff --git a/packages/xforms-engine/src/client/serialization/InstanceData.ts b/packages/xforms-engine/src/client/serialization/InstanceData.ts
new file mode 100644
index 00000000..292173ae
--- /dev/null
+++ b/packages/xforms-engine/src/client/serialization/InstanceData.ts
@@ -0,0 +1,9 @@
+import type { INSTANCE_FILE_NAME, InstanceFile } from './InstanceFile.ts';
+
+export interface InstanceData extends FormData {
+	get(name: INSTANCE_FILE_NAME): InstanceFile;
+	get(name: string): FormDataEntryValue | null;
+
+	has(name: INSTANCE_FILE_NAME): true;
+	has(name: string): boolean;
+}
diff --git a/packages/xforms-engine/src/client/serialization/InstanceFile.ts b/packages/xforms-engine/src/client/serialization/InstanceFile.ts
new file mode 100644
index 00000000..5a047033
--- /dev/null
+++ b/packages/xforms-engine/src/client/serialization/InstanceFile.ts
@@ -0,0 +1,9 @@
+import type { INSTANCE_FILE_NAME, INSTANCE_FILE_TYPE } from '../constants.ts';
+
+// Re-export for convenient `InstanceFile` construction/access flows
+export type { INSTANCE_FILE_NAME, INSTANCE_FILE_TYPE };
+
+export interface InstanceFile extends File {
+	readonly name: INSTANCE_FILE_NAME;
+	readonly type: INSTANCE_FILE_TYPE;
+}
diff --git a/packages/xforms-engine/src/client/serialization/InstancePayload.ts b/packages/xforms-engine/src/client/serialization/InstancePayload.ts
new file mode 100644
index 00000000..9d401d36
--- /dev/null
+++ b/packages/xforms-engine/src/client/serialization/InstancePayload.ts
@@ -0,0 +1,124 @@
+import type { SubmissionDefinition } from '../submission/SubmissionDefinition.ts';
+import type { AnyViolation, DescendantNodeViolationReference } from '../validation.ts';
+import type { InstanceData } from './InstanceData.ts';
+import type { InstancePayloadOptions, InstancePayloadType } from './InstancePayloadOptions.ts';
+
+// prettier-ignore
+export type InstancePayloadStatus =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| 'pending'
+	| 'max-size-exceeded'
+	| 'ready';
+
+// prettier-ignore
+type InstancePayloadData<PayloadType extends InstancePayloadType> = {
+	chunked: readonly [InstanceData, ...InstanceData[]];
+	monolithic: InstanceData;
+}[PayloadType];
+
+/**
+ * Provides detail about an individual instance attachment {@link File}s which
+ * exceeds the client-specified {@link maxSize} for a
+ * {@link ChunkedInstancePayload | chunked instance payload}. Clients may use
+ * this value to provide guidance to users.
+ *
+ * @todo We may want to consider (a) making {@link maxSize} a configuration the
+ * client can provide when initializing a form instance, rather than only when
+ * serializing an instance payload; and then (b) treating a maximum size
+ * violation as another kind of node-level violation. This would go beyond the
+ * kinds of validation specified by ODK XForms, but it would make a lot of
+ * _conceptual sense_.
+ *
+ * It would almost certainly be helpful to alert users to violations as the
+ * occur, rather than only at instance payload serialization time (where they
+ * have likely already moved on). This is something clients can do without
+ * engine support, but it would likely promote good usability patterns if the
+ * engine makes it an obvious and uniform option at the main engine/client
+ * entrypoint.
+ *
+ * @todo If we consider the above, we'd want to reframe _this interface_ to
+ * match the shape of other {@link AnyViolation | violations} (adding it as a
+ * member of that union). We'd also likely eliminate
+ * {@link MaxSizeExceededResult} in the process, since
+ * {@link PendingInstancePayload} would then cover the case.
+ */
+interface MaxSizeViolation {
+	/**
+	 * Specifies the index of
+	 * {@link InstancePayloadData<'chunked'> | chunked instance payload data}
+	 * where an instance attachment {@link File} exceeds the client-specified
+	 * {@link maxSize}.
+	 */
+	readonly dataIndex: number;
+
+	/**
+	 * Specifies the name of the file which exceeds the client-specified
+	 * {@link maxSize}. This name can also be used as a key to access the
+	 * violating {@link File}/instance attachment, in the {@link InstanceData} at
+	 * the specified {@link dataIndex}.
+	 */
+	readonly fileName: string;
+
+	/**
+	 * Reflects the client-specified maximum size for each chunk of a
+	 * {@link ChunkedInstancePayload | chunked instance payload}.
+	 */
+	readonly maxSize: number;
+
+	/**
+	 * Details the actual size of the violating {@link File}/instance attachment.
+	 * Along with {@link maxSize}. Clients may use the delta between this value
+	 * and {@link maxSize} to provide detailed guidance to users.
+	 */
+	readonly actualSize: number;
+}
+
+// prettier-ignore
+type InstancePayloadViolation =
+	| DescendantNodeViolationReference
+	| MaxSizeViolation;
+
+interface BaseInstancePayload<PayloadType extends InstancePayloadType> {
+	readonly status: InstancePayloadStatus;
+	readonly definition: SubmissionDefinition;
+	get violations(): readonly InstancePayloadViolation[] | null;
+
+	/**
+	 * Instance attachment data may be chunked according to the
+	 * {@link InstancePayloadOptions.maxSize | maxSize instance payload option}
+	 */
+	readonly data: InstancePayloadData<PayloadType>;
+}
+
+interface PendingInstancePayload<PayloadType extends InstancePayloadType>
+	extends BaseInstancePayload<PayloadType> {
+	readonly status: 'pending';
+	get violations(): readonly DescendantNodeViolationReference[];
+}
+
+interface MaxSizeExceededResult extends BaseInstancePayload<'chunked'> {
+	readonly status: 'max-size-exceeded';
+	get violations(): readonly MaxSizeViolation[];
+}
+
+interface ReadyInstancePayload<PayloadType extends InstancePayloadType>
+	extends BaseInstancePayload<PayloadType> {
+	readonly status: 'ready';
+	get violations(): null;
+}
+
+// prettier-ignore
+export type ChunkedInstancePayload =
+	| MaxSizeExceededResult
+	| PendingInstancePayload<'chunked'>
+	| ReadyInstancePayload<'chunked'>;
+
+export type MonolithicInstancePayload =
+	| PendingInstancePayload<'monolithic'>
+	| ReadyInstancePayload<'monolithic'>;
+
+// prettier-ignore
+export type InstancePayload<PayloadType extends InstancePayloadType> = {
+	chunked: ChunkedInstancePayload;
+	monolithic: MonolithicInstancePayload;
+}[PayloadType];
diff --git a/packages/xforms-engine/src/client/serialization/InstancePayloadOptions.ts b/packages/xforms-engine/src/client/serialization/InstancePayloadOptions.ts
new file mode 100644
index 00000000..ade703f8
--- /dev/null
+++ b/packages/xforms-engine/src/client/serialization/InstancePayloadOptions.ts
@@ -0,0 +1,28 @@
+export type InstancePayloadType = 'chunked' | 'monolithic';
+
+interface BaseInstancePayloadOptions<PayloadType extends InstancePayloadType> {
+	readonly payloadType?: PayloadType | undefined;
+
+	/**
+	 * As described in the
+	 * {@link https://docs.getodk.org/openrosa-form-submission/#extended-transmission-considerations | OpenRosa Form Submission API},
+	 * clients may obtain this value from an OpenRosa server's
+	 * `X-OpenRosa-Accept-Content-Length` header.
+	 */
+	readonly maxSize?: number;
+}
+
+interface ChunkedInstancePayloadOptions extends BaseInstancePayloadOptions<'chunked'> {
+	readonly maxSize: number;
+}
+
+interface MonolithicInstancePayloadOptions extends BaseInstancePayloadOptions<'monolithic'> {
+	readonly payloadType?: 'monolithic' | undefined;
+	readonly maxSize?: never;
+}
+
+// prettier-ignore
+export type InstancePayloadOptions<PayloadType extends InstancePayloadType = 'monolithic'> = {
+	chunked: ChunkedInstancePayloadOptions;
+	monolithic: MonolithicInstancePayloadOptions;
+}[PayloadType];
diff --git a/packages/xforms-engine/src/client/serialization/InstanceState.ts b/packages/xforms-engine/src/client/serialization/InstanceState.ts
new file mode 100644
index 00000000..eab0cb56
--- /dev/null
+++ b/packages/xforms-engine/src/client/serialization/InstanceState.ts
@@ -0,0 +1,14 @@
+import type { RootNode } from '../RootNode.ts';
+
+export interface InstanceState {
+	/**
+	 * Represents the serialized XML state of a given node. The value produced in
+	 * {@link RootNode.instanceState} is the same serialization which will be
+	 * produced for a complete instance.
+	 *
+	 * @todo Note that this particular aspect of the design doesn't yet address
+	 * production of unique file names. As such, this may change as we introduce
+	 * affected data types (and their supporting nodes).
+	 */
+	get instanceXML(): string;
+}
diff --git a/packages/xforms-engine/src/client/submission/SubmissionData.ts b/packages/xforms-engine/src/client/submission/SubmissionData.ts
deleted file mode 100644
index d9dcb340..00000000
--- a/packages/xforms-engine/src/client/submission/SubmissionData.ts
+++ /dev/null
@@ -1,12 +0,0 @@
-import type {
-	SubmissionInstanceFile,
-	SubmissionInstanceFileName,
-} from './SubmissionInstanceFile.ts';
-
-export interface SubmissionData extends FormData {
-	get(name: SubmissionInstanceFileName): SubmissionInstanceFile;
-	get(name: string): FormDataEntryValue | null;
-
-	has(name: SubmissionInstanceFileName): true;
-	has(name: string): boolean;
-}
diff --git a/packages/xforms-engine/src/client/submission/SubmissionInstanceFile.ts b/packages/xforms-engine/src/client/submission/SubmissionInstanceFile.ts
deleted file mode 100644
index 6cd115a2..00000000
--- a/packages/xforms-engine/src/client/submission/SubmissionInstanceFile.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-import type { SubmissionInstanceFileName, SubmissionInstanceFileType } from '../constants.ts';
-
-// Re-export for convenient `SubmissionInstanceFile` construction/access flows
-export type { SubmissionInstanceFileName, SubmissionInstanceFileType };
-
-export interface SubmissionInstanceFile extends File {
-	readonly name: SubmissionInstanceFileName;
-	readonly type: SubmissionInstanceFileType;
-}
diff --git a/packages/xforms-engine/src/client/submission/SubmissionOptions.ts b/packages/xforms-engine/src/client/submission/SubmissionOptions.ts
deleted file mode 100644
index 13184d37..00000000
--- a/packages/xforms-engine/src/client/submission/SubmissionOptions.ts
+++ /dev/null
@@ -1,28 +0,0 @@
-export type SubmissionChunkedType = 'chunked' | 'monolithic';
-
-interface BaseSubmissionOptions<ChunkedType extends SubmissionChunkedType> {
-	readonly chunked?: ChunkedType | undefined;
-
-	/**
-	 * As described in the
-	 * {@link https://docs.getodk.org/openrosa-form-submission/#extended-transmission-considerations | OpenRosa Form Submission API},
-	 * clients may obtain this value from an OpenRosa server's
-	 * `X-OpenRosa-Accept-Content-Length` header.
-	 */
-	readonly maxSize?: number;
-}
-
-interface ChunkedSubmissionOptions extends BaseSubmissionOptions<'chunked'> {
-	readonly maxSize: number;
-}
-
-interface MonolithicSubmissionOptions extends BaseSubmissionOptions<'monolithic'> {
-	readonly chunked?: 'monolithic' | undefined;
-	readonly maxSize?: never;
-}
-
-// prettier-ignore
-export type SubmissionOptions<ChunkedType extends SubmissionChunkedType = 'monolithic'> = {
-	chunked: ChunkedSubmissionOptions;
-	monolithic: MonolithicSubmissionOptions;
-}[ChunkedType];
diff --git a/packages/xforms-engine/src/client/submission/SubmissionResult.ts b/packages/xforms-engine/src/client/submission/SubmissionResult.ts
deleted file mode 100644
index 54437d41..00000000
--- a/packages/xforms-engine/src/client/submission/SubmissionResult.ts
+++ /dev/null
@@ -1,124 +0,0 @@
-import type { AnyViolation, DescendantNodeViolationReference } from '../validation.ts';
-import type { SubmissionData } from './SubmissionData.ts';
-import type { SubmissionDefinition } from './SubmissionDefinition.ts';
-import type { SubmissionChunkedType, SubmissionOptions } from './SubmissionOptions.ts';
-
-// prettier-ignore
-export type SubmissionResultStatus =
-	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
-	| 'pending'
-	| 'max-size-exceeded'
-	| 'ready';
-
-// prettier-ignore
-type SubmissionResultData<ChunkedType extends SubmissionChunkedType> = {
-	chunked: readonly [SubmissionData, ...SubmissionData[]];
-	monolithic: SubmissionData;
-}[ChunkedType];
-
-/**
- * Provides detail about an individual submission attachment {@link File}s which
- * exceeds the client-specified {@link maxSize} for a
- * {@link SubmissionResult<'chunked'> | chunked submission result}. Clients may
- * use this value to provide guidance to users.
- *
- * @todo We may want to consider (a) making {@link maxSize} a configuration the
- * client can provide when initializing a form instance, rather than only on
- * submission; and then (b) treating a maximum size violation as another kind of
- * node-level violation. This would go beyond the kinds of validation specified
- * by ODK XForms, but it would make a lot of _conceptual sense_.
- *
- * It would almost certainly be helpful to alert users to violations as the
- * occur, rather than only at submission time (where they have likely already
- * moved on). This is something clients can do without engine support, but it
- * would likely promote good usability patterns if the engine makes it an
- * obvious and uniform option at the main engine/client entrypoint.
- *
- * @todo If we consider the above, we'd want to reframe _this interface_ to
- * match the shape of other {@link AnyViolation | violations} (adding it as a
- * member of that union). We'd also likely eliminate
- * {@link MaxSizeExceededResult} in the process, since
- * {@link PendingSubmissionResult} would then cover the case.
- */
-interface MaxSizeViolation {
-	/**
-	 * Specifies the index of
-	 * {@link SubmissionResultData<'chunked'> | chunked submission data} where a
-	 * submission attachment {@link File} exceeds the client-specified
-	 * {@link maxSize}.
-	 */
-	readonly dataIndex: number;
-
-	/**
-	 * Specifies the name of the file which exceeds the client-specified
-	 * {@link maxSize}. This name can also be used as a key to access the
-	 * violating {@link File}/submission attachment, in the {@link SubmissionData}
-	 * at the specified {@link dataIndex}.
-	 */
-	readonly fileName: string;
-
-	/**
-	 * Reflects the client-specified maximum size for each chunk of a
-	 * {@link SubmissionResult<'chunked'> | chunked submission result}.
-	 */
-	readonly maxSize: number;
-
-	/**
-	 * Details the actual size of the violating {@link File}/submission
-	 * attachment. Along with {@link maxSize}. Clients may use the delta between
-	 * this value and {@link maxSize} to provide detailed guidance to users.
-	 */
-	readonly actualSize: number;
-}
-
-// prettier-ignore
-type SubmissionResultViolation =
-	| DescendantNodeViolationReference
-	| MaxSizeViolation;
-
-interface BaseSubmissionResult<ChunkedType extends SubmissionChunkedType> {
-	readonly status: SubmissionResultStatus;
-	readonly definition: SubmissionDefinition;
-	get violations(): readonly SubmissionResultViolation[] | null;
-
-	/**
-	 * Submission data may be chunked according to the
-	 * {@link SubmissionOptions.maxSize | maxSize submission option}
-	 */
-	readonly data: SubmissionResultData<ChunkedType>;
-}
-
-interface PendingSubmissionResult<ChunkedType extends SubmissionChunkedType>
-	extends BaseSubmissionResult<ChunkedType> {
-	readonly status: 'pending';
-	get violations(): readonly DescendantNodeViolationReference[];
-}
-
-interface MaxSizeExceededResult extends BaseSubmissionResult<'chunked'> {
-	readonly status: 'max-size-exceeded';
-	get violations(): readonly MaxSizeViolation[];
-}
-
-interface ReadySubmissionResult<ChunkedType extends SubmissionChunkedType>
-	extends BaseSubmissionResult<ChunkedType> {
-	readonly status: 'ready';
-	get violations(): null;
-}
-
-// prettier-ignore
-type CommonSubmissionResult<ChunkedType extends SubmissionChunkedType> =
-	| PendingSubmissionResult<ChunkedType>
-	| ReadySubmissionResult<ChunkedType>;
-
-// prettier-ignore
-export type ChunkedSubmissionResult =
-	| CommonSubmissionResult<'chunked'>
-	| MaxSizeExceededResult;
-
-export type MonolithicSubmissionResult = CommonSubmissionResult<'monolithic'>;
-
-// prettier-ignore
-export type SubmissionResult<ChunkedType extends SubmissionChunkedType> = {
-	chunked: ChunkedSubmissionResult;
-	monolithic: MonolithicSubmissionResult;
-}[ChunkedType];
diff --git a/packages/xforms-engine/src/client/submission/SubmissionState.ts b/packages/xforms-engine/src/client/submission/SubmissionState.ts
deleted file mode 100644
index 5944fd84..00000000
--- a/packages/xforms-engine/src/client/submission/SubmissionState.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import type { RootNode } from '../RootNode.ts';
-
-export interface SubmissionState {
-	/**
-	 * Represents the serialized XML state of a given node, as it will be prepared
-	 * for submission. The value produced in {@link RootNode.submissionState} is
-	 * the same serialization which will be produced for the complete submission.
-	 *
-	 * @todo Note that this particular aspect of the design doesn't yet address
-	 * production of unique file names. As such, this may change as we introduce
-	 * affected data types (and their supporting nodes).
-	 */
-	get submissionXML(): string;
-}
diff --git a/packages/xforms-engine/src/index.ts b/packages/xforms-engine/src/index.ts
index 5836b5a6..1f7e5e2f 100644
--- a/packages/xforms-engine/src/index.ts
+++ b/packages/xforms-engine/src/index.ts
@@ -25,22 +25,22 @@ export type * from './client/ModelValueNode.ts';
 export type * from './client/NoteNode.ts';
 export type * from './client/OpaqueReactiveObjectFactory.ts';
 export type * from './client/RangeNode.ts';
+export type * from './client/RankNode.ts';
 export type * from './client/repeat/RepeatInstanceNode.ts';
 export type * from './client/repeat/RepeatRangeControlledNode.ts';
 export type * from './client/repeat/RepeatRangeUncontrolledNode.ts';
 export type * from './client/resources.ts';
 export type * from './client/RootNode.ts';
 export type * from './client/SelectNode.ts';
-export type * from './client/submission/SubmissionData.ts';
+export type * from './client/serialization/InstanceData.ts';
+export type * from './client/serialization/InstanceFile.ts';
+export type * from './client/serialization/InstancePayload.ts';
+export type * from './client/serialization/InstancePayloadOptions.ts';
+export type * from './client/serialization/InstanceState.ts';
 export type * from './client/submission/SubmissionDefinition.ts';
-export type * from './client/submission/SubmissionInstanceFile.ts';
-export type * from './client/submission/SubmissionOptions.ts';
-export type * from './client/submission/SubmissionResult.ts';
-export type * from './client/submission/SubmissionState.ts';
 export type * from './client/SubtreeNode.ts';
 export type * from './client/TextRange.ts';
 export type * from './client/TriggerNode.ts';
-export type * from './client/RankNode.ts';
 export type * from './client/unsupported/UploadNode.ts';
 export type * from './client/validation.ts';
 export type * from './client/ValueType.ts';
diff --git a/packages/xforms-engine/src/instance/Group.ts b/packages/xforms-engine/src/instance/Group.ts
index b19895bd..b2729a70 100644
--- a/packages/xforms-engine/src/instance/Group.ts
+++ b/packages/xforms-engine/src/instance/Group.ts
@@ -2,7 +2,7 @@ import { XPathNodeKindKey } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
 import type { GroupDefinition, GroupNode, GroupNodeAppearances } from '../client/GroupNode.ts';
 import type { FormNodeID } from '../client/identity.ts';
-import type { SubmissionState } from '../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../client/serialization/InstanceState.ts';
 import type { TextRange } from '../client/TextRange.ts';
 import type { AncestorNodeValidationState } from '../client/validation.ts';
 import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
@@ -55,7 +55,7 @@ export class Group
 	readonly nodeOptions = null;
 	readonly currentState: MaterializedChildren<CurrentState<GroupStateSpec>, GeneralChildNode>;
 	readonly validationState: AncestorNodeValidationState;
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 
 	constructor(parent: GeneralParentNode, definition: GroupDefinition) {
 		super(parent, definition);
@@ -97,7 +97,7 @@ export class Group
 
 		childrenState.setChildren(buildChildren(this));
 		this.validationState = createAggregatedViolations(this, sharedStateOptions);
-		this.submissionState = createParentNodeSubmissionState(this);
+		this.instanceState = createParentNodeSubmissionState(this);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {
diff --git a/packages/xforms-engine/src/instance/PrimaryInstance.ts b/packages/xforms-engine/src/instance/PrimaryInstance.ts
index 1bffd317..ebb41479 100644
--- a/packages/xforms-engine/src/instance/PrimaryInstance.ts
+++ b/packages/xforms-engine/src/instance/PrimaryInstance.ts
@@ -4,12 +4,12 @@ import { createSignal } from 'solid-js';
 import type { ActiveLanguage, FormLanguage, FormLanguages } from '../client/FormLanguage.ts';
 import type { FormNodeID } from '../client/identity.ts';
 import type { RootNode } from '../client/RootNode.ts';
+import type { InstancePayload } from '../client/serialization/InstancePayload.ts';
 import type {
-	SubmissionChunkedType,
-	SubmissionOptions,
-} from '../client/submission/SubmissionOptions.ts';
-import type { SubmissionResult } from '../client/submission/SubmissionResult.ts';
-import type { SubmissionState } from '../client/submission/SubmissionState.ts';
+	InstancePayloadOptions,
+	InstancePayloadType,
+} from '../client/serialization/InstancePayloadOptions.ts';
+import type { InstanceState } from '../client/serialization/InstanceState.ts';
 import type { AncestorNodeValidationState } from '../client/validation.ts';
 import type { XFormsXPathDocument } from '../integration/xpath/adapter/XFormsXPathNode.ts';
 import { EngineXPathEvaluator } from '../integration/xpath/EngineXPathEvaluator.ts';
@@ -107,7 +107,7 @@ export class PrimaryInstance
 	readonly root: Root;
 	readonly currentState: MaterializedChildren<CurrentState<PrimaryInstanceStateSpec>, Root>;
 	readonly validationState: AncestorNodeValidationState;
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 	readonly languages: FormLanguages;
 
 	// TranslationContext (+ EvaluationContext)
@@ -187,7 +187,7 @@ export class PrimaryInstance
 				return root.validationState.violations;
 			},
 		};
-		this.submissionState = createInstanceSubmissionState(this);
+		this.instanceState = createInstanceSubmissionState(this);
 
 		childrenState.setChildren([root]);
 		setIsAttached(true);
@@ -231,12 +231,12 @@ export class PrimaryInstance
 		return this.setActiveLanguage(availableFormLanguage);
 	}
 
-	// PrimaryInstanceDocument, ClientReactiveSubmittableInstance
-	prepareSubmission<ChunkedType extends SubmissionChunkedType = 'monolithic'>(
-		options?: SubmissionOptions<ChunkedType>
-	): Promise<SubmissionResult<ChunkedType>> {
+	// PrimaryInstanceDocument
+	prepareInstancePayload<PayloadType extends InstancePayloadType = 'monolithic'>(
+		options?: InstancePayloadOptions<PayloadType>
+	): Promise<InstancePayload<PayloadType>> {
 		const result = prepareSubmission(this, {
-			chunked: (options?.chunked ?? 'monolithic') as ChunkedType,
+			payloadType: (options?.payloadType ?? 'monolithic') as PayloadType,
 			maxSize: options?.maxSize ?? Infinity,
 		});
 
diff --git a/packages/xforms-engine/src/instance/Root.ts b/packages/xforms-engine/src/instance/Root.ts
index c971a6fe..36fe4a68 100644
--- a/packages/xforms-engine/src/instance/Root.ts
+++ b/packages/xforms-engine/src/instance/Root.ts
@@ -3,12 +3,12 @@ import type { Accessor } from 'solid-js';
 import type { ActiveLanguage, FormLanguage, FormLanguages } from '../client/FormLanguage.ts';
 import type { FormNodeID } from '../client/identity.ts';
 import type { RootNode } from '../client/RootNode.ts';
+import type { InstancePayload } from '../client/serialization/InstancePayload.ts';
 import type {
-	SubmissionChunkedType,
-	SubmissionOptions,
-} from '../client/submission/SubmissionOptions.ts';
-import type { SubmissionResult } from '../client/submission/SubmissionResult.ts';
-import type { SubmissionState } from '../client/submission/SubmissionState.ts';
+	InstancePayloadOptions,
+	InstancePayloadType,
+} from '../client/serialization/InstancePayloadOptions.ts';
+import type { InstanceState } from '../client/serialization/InstanceState.ts';
 import type { AncestorNodeValidationState } from '../client/validation.ts';
 import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
 import { createRootSubmissionState } from '../lib/client-reactivity/submission/createRootSubmissionState.ts';
@@ -79,7 +79,7 @@ export class Root
 	readonly classes: BodyClassList;
 	readonly currentState: MaterializedChildren<CurrentState<RootStateSpec>, GeneralChildNode>;
 	readonly validationState: AncestorNodeValidationState;
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 	readonly languages: FormLanguages;
 
 	constructor(parent: PrimaryInstance) {
@@ -129,7 +129,7 @@ export class Root
 
 		childrenState.setChildren(buildChildren(this));
 		this.validationState = createAggregatedViolations(this, sharedStateOptions);
-		this.submissionState = createRootSubmissionState(this);
+		this.instanceState = createRootSubmissionState(this);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {
@@ -143,9 +143,9 @@ export class Root
 		return this;
 	}
 
-	prepareSubmission<ChunkedType extends SubmissionChunkedType = 'monolithic'>(
-		options?: SubmissionOptions<ChunkedType>
-	): Promise<SubmissionResult<ChunkedType>> {
-		return this.rootDocument.prepareSubmission(options);
+	prepareInstancePayload<PayloadType extends InstancePayloadType = 'monolithic'>(
+		options?: InstancePayloadOptions<PayloadType>
+	): Promise<InstancePayload<PayloadType>> {
+		return this.rootDocument.prepareInstancePayload(options);
 	}
 }
diff --git a/packages/xforms-engine/src/instance/Subtree.ts b/packages/xforms-engine/src/instance/Subtree.ts
index 1265c993..92ed4991 100644
--- a/packages/xforms-engine/src/instance/Subtree.ts
+++ b/packages/xforms-engine/src/instance/Subtree.ts
@@ -1,7 +1,7 @@
 import { XPathNodeKindKey } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
 import type { FormNodeID } from '../client/identity.ts';
-import type { SubmissionState } from '../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../client/serialization/InstanceState.ts';
 import type { SubtreeDefinition, SubtreeNode } from '../client/SubtreeNode.ts';
 import type { AncestorNodeValidationState } from '../client/validation.ts';
 import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
@@ -52,7 +52,7 @@ export class Subtree
 	readonly nodeOptions = null;
 	readonly currentState: MaterializedChildren<CurrentState<SubtreeStateSpec>, GeneralChildNode>;
 	readonly validationState: AncestorNodeValidationState;
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 
 	constructor(parent: GeneralParentNode, definition: SubtreeDefinition) {
 		super(parent, definition);
@@ -92,7 +92,7 @@ export class Subtree
 
 		childrenState.setChildren(buildChildren(this));
 		this.validationState = createAggregatedViolations(this, sharedStateOptions);
-		this.submissionState = createParentNodeSubmissionState(this);
+		this.instanceState = createParentNodeSubmissionState(this);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {
diff --git a/packages/xforms-engine/src/instance/abstract/InstanceNode.ts b/packages/xforms-engine/src/instance/abstract/InstanceNode.ts
index 2d5fdf2e..aae61dd4 100644
--- a/packages/xforms-engine/src/instance/abstract/InstanceNode.ts
+++ b/packages/xforms-engine/src/instance/abstract/InstanceNode.ts
@@ -4,7 +4,7 @@ import type { BaseNode } from '../../client/BaseNode.ts';
 import type { NodeAppearances } from '../../client/NodeAppearances.ts';
 import type { FormNodeID } from '../../client/identity.ts';
 import type { InstanceNodeType as ClientInstanceNodeType } from '../../client/node-types.ts';
-import type { SubmissionState } from '../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../client/serialization/InstanceState.ts';
 import type { NodeValidationState } from '../../client/validation.ts';
 import type { ActiveLanguage, TextRange } from '../../index.ts';
 import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
@@ -148,7 +148,7 @@ export abstract class InstanceNode<
 
 	abstract readonly validationState: NodeValidationState;
 
-	abstract readonly submissionState: SubmissionState;
+	abstract readonly instanceState: InstanceState;
 
 	// EvaluationContext: instance-global/shared
 	abstract readonly evaluator: EngineXPathEvaluator;
diff --git a/packages/xforms-engine/src/instance/abstract/UnsupportedControl.ts b/packages/xforms-engine/src/instance/abstract/UnsupportedControl.ts
index 82d2797c..6ff87c15 100644
--- a/packages/xforms-engine/src/instance/abstract/UnsupportedControl.ts
+++ b/packages/xforms-engine/src/instance/abstract/UnsupportedControl.ts
@@ -2,7 +2,7 @@ import { identity } from '@getodk/common/lib/identity.ts';
 import { XPathNodeKindKey } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
 import type { UnsupportedControlNodeType } from '../../client/node-types.ts';
-import type { SubmissionState } from '../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../client/serialization/InstanceState.ts';
 import type { TextRange } from '../../client/TextRange.ts';
 import type {
 	UnsupportedControlDefinition,
@@ -99,7 +99,7 @@ export abstract class UnsupportedControl<Type extends UnsupportedControlNodeType
 		return this.validation.currentState;
 	}
 
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 
 	// ValueContext
 	abstract override readonly contextNode: AnyUnsupportedControl & this;
@@ -146,7 +146,7 @@ export abstract class UnsupportedControl<Type extends UnsupportedControlNodeType
 		this.engineState = state.engineState;
 		this.currentState = state.currentState;
 		this.validation = createValidationState(this, sharedStateOptions);
-		this.submissionState = createLeafNodeSubmissionState(this);
+		this.instanceState = createLeafNodeSubmissionState(this);
 	}
 
 	// XFormsXPathElement
diff --git a/packages/xforms-engine/src/instance/abstract/ValueNode.ts b/packages/xforms-engine/src/instance/abstract/ValueNode.ts
index 10bb9c37..bb5ec3ef 100644
--- a/packages/xforms-engine/src/instance/abstract/ValueNode.ts
+++ b/packages/xforms-engine/src/instance/abstract/ValueNode.ts
@@ -2,7 +2,7 @@ import { XPathNodeKindKey } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
 import type { BaseValueNode } from '../../client/BaseValueNode.ts';
 import type { LeafNodeType as ValueNodeType } from '../../client/node-types.ts';
-import type { SubmissionState } from '../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../client/serialization/InstanceState.ts';
 import type { AnyViolation, LeafNodeValidationState } from '../../client/validation.ts';
 import type { ValueType } from '../../client/ValueType.ts';
 import type { XFormsXPathElement } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
@@ -80,7 +80,7 @@ export abstract class ValueNode<
 		return this.validation.currentState;
 	}
 
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 
 	constructor(
 		parent: GeneralParentNode,
@@ -109,7 +109,7 @@ export abstract class ValueNode<
 		this.validation = createValidationState(this, {
 			clientStateFactory: this.engineConfig.stateFactory,
 		});
-		this.submissionState = createValueNodeSubmissionState(this);
+		this.instanceState = createValueNodeSubmissionState(this);
 	}
 
 	// ValidationContext
diff --git a/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableLeafNode.ts b/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableLeafNode.ts
index 6b4b3aae..362ed7d2 100644
--- a/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableLeafNode.ts
+++ b/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableLeafNode.ts
@@ -1,4 +1,4 @@
-import type { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
 import type { QualifiedName } from '../../../lib/names/QualifiedName.ts';
 import type { EscapedXMLText } from '../../../lib/xml-serialization.ts';
 import type {
@@ -24,11 +24,11 @@ export interface ClientReactiveSubmittableLeafNode<RuntimeValue> {
 
 	/**
 	 * A client-reactive submittable leaf node is responsible for producing a
-	 * string representation of its value state, suitable for serialization for
-	 * submission. It **MUST NOT** perform any further submission-specific
-	 * serialization duties: in particular, the value **MUST NOT** be escaped for
-	 * XML. This responsibility is delegated up the stack, to avoid repeat
-	 * escaping.
+	 * string representation of its value state, suitable for instance
+	 * serialization. It **MUST NOT** perform any further instance
+	 * serialization-specific serialization duties: in particular, the value
+	 * **MUST NOT** be escaped for XML. This responsibility is delegated up the
+	 * stack, to avoid repeat escaping.
 	 *
 	 * Note: excluding {@link EscapedXMLText} here does not have an effect on the
 	 * type system, it is a documentation-only hint, to help guard against future
@@ -39,5 +39,5 @@ export interface ClientReactiveSubmittableLeafNode<RuntimeValue> {
 		runtimeValue: RuntimeValue
 	) => Exclude<string, EscapedXMLText>;
 
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 }
diff --git a/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableParentNode.ts b/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableParentNode.ts
index b4a18f49..692556b4 100644
--- a/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableParentNode.ts
+++ b/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableParentNode.ts
@@ -1,8 +1,8 @@
-import type { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
 import type { QualifiedName } from '../../../lib/names/QualifiedName.ts';
 
 export interface ClientReactiveSubmittableChildNode {
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 }
 
 interface ClientReactiveSubmittableParentNodeCurrentState<
@@ -22,5 +22,5 @@ export interface ClientReactiveSubmittableParentNode<
 	readonly definition: ClientReactiveSubmittableParentNodeDefinition;
 	readonly parent: ClientReactiveSubmittableParentNode<ClientReactiveSubmittableChildNode> | null;
 	readonly currentState: ClientReactiveSubmittableParentNodeCurrentState<Child>;
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 }
diff --git a/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableValueNode.ts b/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableValueNode.ts
index c9f847e5..ba924447 100644
--- a/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableValueNode.ts
+++ b/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableValueNode.ts
@@ -1,4 +1,4 @@
-import type { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
 import type { QualifiedName } from '../../../lib/names/QualifiedName.ts';
 import type {
 	ClientReactiveSubmittableChildNode,
@@ -7,6 +7,10 @@ import type {
 
 interface ClientReactiveSubmittableValueNodeCurrentState {
 	get relevant(): boolean;
+
+	/**
+	 * @todo Consider moving into {@link InstanceState}
+	 */
 	get instanceValue(): string;
 }
 
@@ -20,5 +24,5 @@ export interface ClientReactiveSubmittableValueNode {
 	readonly definition: ClientReactiveSubmittableValueNodeDefinition;
 	readonly parent: ClientReactiveSubmittableParentNode<ClientReactiveSubmittableChildNode>;
 	readonly currentState: ClientReactiveSubmittableValueNodeCurrentState;
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 }
diff --git a/packages/xforms-engine/src/instance/repeat/BaseRepeatRange.ts b/packages/xforms-engine/src/instance/repeat/BaseRepeatRange.ts
index aa071a10..aaa71c3d 100644
--- a/packages/xforms-engine/src/instance/repeat/BaseRepeatRange.ts
+++ b/packages/xforms-engine/src/instance/repeat/BaseRepeatRange.ts
@@ -6,7 +6,7 @@ import type { RepeatRangeNode } from '../../client/hierarchy.ts';
 import type { FormNodeID } from '../../client/identity.ts';
 import type { NodeAppearances } from '../../client/NodeAppearances.ts';
 import type { BaseRepeatRangeNode } from '../../client/repeat/BaseRepeatRangeNode.ts';
-import type { SubmissionState } from '../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../client/serialization/InstanceState.ts';
 import type { TextRange } from '../../client/TextRange.ts';
 import type { AncestorNodeValidationState } from '../../client/validation.ts';
 import type {
@@ -149,7 +149,7 @@ export abstract class BaseRepeatRange<Definition extends AnyRepeatRangeDefinitio
 
 	abstract override readonly validationState: AncestorNodeValidationState;
 
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 
 	constructor(parent: GeneralParentNode, definition: Definition) {
 		super(parent, definition);
@@ -188,7 +188,7 @@ export abstract class BaseRepeatRange<Definition extends AnyRepeatRangeDefinitio
 			state.currentState,
 			childrenState
 		);
-		this.submissionState = createNodeRangeSubmissionState(this);
+		this.instanceState = createNodeRangeSubmissionState(this);
 	}
 
 	protected getLastIndex(): number {
diff --git a/packages/xforms-engine/src/instance/repeat/RepeatInstance.ts b/packages/xforms-engine/src/instance/repeat/RepeatInstance.ts
index c8ff7333..654110c7 100644
--- a/packages/xforms-engine/src/instance/repeat/RepeatInstance.ts
+++ b/packages/xforms-engine/src/instance/repeat/RepeatInstance.ts
@@ -7,7 +7,7 @@ import type {
 	RepeatInstanceNode,
 	RepeatInstanceNodeAppearances,
 } from '../../client/repeat/RepeatInstanceNode.ts';
-import type { SubmissionState } from '../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../client/serialization/InstanceState.ts';
 import type { TextRange } from '../../client/TextRange.ts';
 import type { AncestorNodeValidationState } from '../../client/validation.ts';
 import type { XFormsXPathElement } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
@@ -99,7 +99,7 @@ export class RepeatInstance
 		GeneralChildNode
 	>;
 	readonly validationState: AncestorNodeValidationState;
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 
 	constructor(
 		override readonly parent: RepeatRange,
@@ -179,7 +179,7 @@ export class RepeatInstance
 
 		childrenState.setChildren(buildChildren(this));
 		this.validationState = createAggregatedViolations(this, sharedStateOptions);
-		this.submissionState = createParentNodeSubmissionState(this);
+		this.instanceState = createParentNodeSubmissionState(this);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {
diff --git a/packages/xforms-engine/src/lib/client-reactivity/submission/createInstanceSubmissionState.ts b/packages/xforms-engine/src/lib/client-reactivity/submission/createInstanceSubmissionState.ts
index 1c42cacf..de5a433e 100644
--- a/packages/xforms-engine/src/lib/client-reactivity/submission/createInstanceSubmissionState.ts
+++ b/packages/xforms-engine/src/lib/client-reactivity/submission/createInstanceSubmissionState.ts
@@ -1,12 +1,12 @@
-import type { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
 import type { ClientReactiveSubmittableInstance } from '../../../instance/internal-api/submission/ClientReactiveSubmittableInstance.ts';
 
 export const createInstanceSubmissionState = (
 	node: ClientReactiveSubmittableInstance
-): SubmissionState => {
+): InstanceState => {
 	return {
-		get submissionXML(): string {
-			return node.root.submissionState.submissionXML;
+		get instanceXML(): string {
+			return node.root.instanceState.instanceXML;
 		},
 	};
 };
diff --git a/packages/xforms-engine/src/lib/client-reactivity/submission/createLeafNodeSubmissionState.ts b/packages/xforms-engine/src/lib/client-reactivity/submission/createLeafNodeSubmissionState.ts
index df366016..39770a95 100644
--- a/packages/xforms-engine/src/lib/client-reactivity/submission/createLeafNodeSubmissionState.ts
+++ b/packages/xforms-engine/src/lib/client-reactivity/submission/createLeafNodeSubmissionState.ts
@@ -1,12 +1,12 @@
-import type { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
 import type { ClientReactiveSubmittableLeafNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableLeafNode.ts';
 import { escapeXMLText, serializeLeafElementXML } from '../../xml-serialization.ts';
 
 export const createLeafNodeSubmissionState = <Value>(
 	node: ClientReactiveSubmittableLeafNode<Value>
-): SubmissionState => {
+): InstanceState => {
 	return {
-		get submissionXML() {
+		get instanceXML() {
 			if (!node.currentState.relevant) {
 				return '';
 			}
diff --git a/packages/xforms-engine/src/lib/client-reactivity/submission/createNodeRangeSubmissionState.ts b/packages/xforms-engine/src/lib/client-reactivity/submission/createNodeRangeSubmissionState.ts
index a460d6d3..4824407d 100644
--- a/packages/xforms-engine/src/lib/client-reactivity/submission/createNodeRangeSubmissionState.ts
+++ b/packages/xforms-engine/src/lib/client-reactivity/submission/createNodeRangeSubmissionState.ts
@@ -1,14 +1,14 @@
-import type { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
 import type { ClientReactiveSubmittableParentNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableParentNode.ts';
 import type { RepeatInstance } from '../../../instance/repeat/RepeatInstance.ts';
 
 export const createNodeRangeSubmissionState = (
 	node: ClientReactiveSubmittableParentNode<RepeatInstance>
-): SubmissionState => {
+): InstanceState => {
 	return {
-		get submissionXML() {
+		get instanceXML() {
 			const serializedChildren = node.currentState.children.map((child) => {
-				return child.submissionState.submissionXML;
+				return child.instanceState.instanceXML;
 			});
 
 			return serializedChildren.join('');
diff --git a/packages/xforms-engine/src/lib/client-reactivity/submission/createParentNodeSubmissionState.ts b/packages/xforms-engine/src/lib/client-reactivity/submission/createParentNodeSubmissionState.ts
index 067eb735..40530c70 100644
--- a/packages/xforms-engine/src/lib/client-reactivity/submission/createParentNodeSubmissionState.ts
+++ b/packages/xforms-engine/src/lib/client-reactivity/submission/createParentNodeSubmissionState.ts
@@ -1,19 +1,19 @@
-import type { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
 import type { GeneralChildNode } from '../../../instance/hierarchy.ts';
 import type { ClientReactiveSubmittableParentNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableParentNode.ts';
 import { serializeParentElementXML } from '../../xml-serialization.ts';
 
 export const createParentNodeSubmissionState = (
 	node: ClientReactiveSubmittableParentNode<GeneralChildNode>
-): SubmissionState => {
+): InstanceState => {
 	return {
-		get submissionXML() {
+		get instanceXML() {
 			if (!node.currentState.relevant) {
 				return '';
 			}
 
 			const serializedChildren = node.currentState.children.map((child) => {
-				return child.submissionState.submissionXML;
+				return child.instanceState.instanceXML;
 			});
 
 			return serializeParentElementXML(node.definition.qualifiedName, serializedChildren);
diff --git a/packages/xforms-engine/src/lib/client-reactivity/submission/createRootSubmissionState.ts b/packages/xforms-engine/src/lib/client-reactivity/submission/createRootSubmissionState.ts
index 2f230b72..06f04e48 100644
--- a/packages/xforms-engine/src/lib/client-reactivity/submission/createRootSubmissionState.ts
+++ b/packages/xforms-engine/src/lib/client-reactivity/submission/createRootSubmissionState.ts
@@ -1,13 +1,13 @@
-import type { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
 import type { Root } from '../../../instance/Root.ts';
 import { serializeParentElementXML } from '../../xml-serialization.ts';
 
-export const createRootSubmissionState = (node: Root): SubmissionState => {
+export const createRootSubmissionState = (node: Root): InstanceState => {
 	return {
-		get submissionXML() {
+		get instanceXML() {
 			const { namespaceDeclarations, attributes } = node.definition;
 			const serializedChildren = node.currentState.children.map((child) => {
-				return child.submissionState.submissionXML;
+				return child.instanceState.instanceXML;
 			});
 
 			return serializeParentElementXML(node.definition.qualifiedName, serializedChildren, {
diff --git a/packages/xforms-engine/src/lib/client-reactivity/submission/createValueNodeSubmissionState.ts b/packages/xforms-engine/src/lib/client-reactivity/submission/createValueNodeSubmissionState.ts
index 0a335351..5c81358a 100644
--- a/packages/xforms-engine/src/lib/client-reactivity/submission/createValueNodeSubmissionState.ts
+++ b/packages/xforms-engine/src/lib/client-reactivity/submission/createValueNodeSubmissionState.ts
@@ -1,14 +1,14 @@
-import type { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
 import type { ClientReactiveSubmittableValueNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableValueNode.ts';
 import { escapeXMLText, serializeLeafElementXML } from '../../xml-serialization.ts';
 
 export const createValueNodeSubmissionState = (
 	node: ClientReactiveSubmittableValueNode
-): SubmissionState => {
+): InstanceState => {
 	const { qualifiedName } = node.definition;
 
 	return {
-		get submissionXML() {
+		get instanceXML() {
 			if (!node.currentState.relevant) {
 				return '';
 			}
diff --git a/packages/xforms-engine/src/lib/client-reactivity/submission/prepareSubmission.ts b/packages/xforms-engine/src/lib/client-reactivity/submission/prepareSubmission.ts
index 3bc85802..76f17496 100644
--- a/packages/xforms-engine/src/lib/client-reactivity/submission/prepareSubmission.ts
+++ b/packages/xforms-engine/src/lib/client-reactivity/submission/prepareSubmission.ts
@@ -1,41 +1,42 @@
 import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
-import {
-	SUBMISSION_INSTANCE_FILE_NAME,
-	SUBMISSION_INSTANCE_FILE_TYPE,
-} from '../../../client/constants.ts';
-import type { SubmissionData } from '../../../client/submission/SubmissionData.ts';
+import { INSTANCE_FILE_NAME, INSTANCE_FILE_TYPE } from '../../../client/constants.ts';
+import type { InstanceData } from '../../../client/serialization/InstanceData.ts';
+import type { InstanceFile as ClientInstanceFile } from '../../../client/serialization/InstanceFile.ts';
+import type {
+	ChunkedInstancePayload,
+	InstancePayload,
+	MonolithicInstancePayload,
+} from '../../../client/serialization/InstancePayload.ts';
+import type { InstancePayloadType } from '../../../client/serialization/InstancePayloadOptions.ts';
 import type { SubmissionDefinition } from '../../../client/submission/SubmissionDefinition.ts';
-import type { SubmissionInstanceFile } from '../../../client/submission/SubmissionInstanceFile.ts';
-import type { SubmissionChunkedType } from '../../../client/submission/SubmissionOptions.ts';
-import type { SubmissionResult } from '../../../client/submission/SubmissionResult.ts';
 import type { DescendantNodeViolationReference } from '../../../client/validation.ts';
 import type { ClientReactiveSubmittableInstance } from '../../../instance/internal-api/submission/ClientReactiveSubmittableInstance.ts';
 
-class InstanceFile extends File implements SubmissionInstanceFile {
-	override readonly name = SUBMISSION_INSTANCE_FILE_NAME;
-	override readonly type = SUBMISSION_INSTANCE_FILE_TYPE;
+class InstanceFile extends File implements ClientInstanceFile {
+	override readonly name = INSTANCE_FILE_NAME;
+	override readonly type = INSTANCE_FILE_TYPE;
 
 	constructor(instanceRoot: ClientReactiveSubmittableInstance) {
-		const { submissionXML } = instanceRoot.submissionState;
+		const { instanceXML } = instanceRoot.instanceState;
 
-		super([submissionXML], SUBMISSION_INSTANCE_FILE_NAME, {
-			type: SUBMISSION_INSTANCE_FILE_TYPE,
+		super([instanceXML], INSTANCE_FILE_NAME, {
+			type: INSTANCE_FILE_TYPE,
 		});
 	}
 }
 
-type AssertSubmissionData = (data: FormData) => asserts data is SubmissionData;
+type AssertSubmissionData = (data: FormData) => asserts data is InstanceData;
 
 const assertSubmissionData: AssertSubmissionData = (data) => {
-	const instanceFile = data.get(SUBMISSION_INSTANCE_FILE_NAME);
+	const instanceFile = data.get(INSTANCE_FILE_NAME);
 
 	if (!(instanceFile instanceof InstanceFile)) {
-		throw new Error(`Invalid SubmissionData`);
+		throw new Error(`Invalid InstanceData`);
 	}
 };
 
 class InstanceSubmissionData extends FormData {
-	static from(instanceFile: InstanceFile, attachments: readonly File[]): SubmissionData {
+	static from(instanceFile: InstanceFile, attachments: readonly File[]): InstanceData {
 		const data = new this(instanceFile, attachments);
 
 		assertSubmissionData(data);
@@ -49,15 +50,13 @@ class InstanceSubmissionData extends FormData {
 	) {
 		super();
 
-		this.set(SUBMISSION_INSTANCE_FILE_NAME, instanceFile);
+		this.set(INSTANCE_FILE_NAME, instanceFile);
 
 		attachments.forEach((attachment) => {
 			const { name } = attachment;
 
-			if (name === SUBMISSION_INSTANCE_FILE_NAME && attachment !== instanceFile) {
-				throw new Error(
-					`Failed to add conflicting attachment with name ${SUBMISSION_INSTANCE_FILE_NAME}`
-				);
+			if (name === INSTANCE_FILE_NAME && attachment !== instanceFile) {
+				throw new Error(`Failed to add conflicting attachment with name ${INSTANCE_FILE_NAME}`);
 			}
 
 			this.set(name, attachment);
@@ -95,12 +94,12 @@ const validateSubmission = (
 	};
 };
 
-const monolithicSubmissionResult = (
+const monolithicInstancePayload = (
 	validation: SubmissionInstanceStateValidation,
 	definition: SubmissionDefinition,
 	instanceFile: InstanceFile,
 	attachments: readonly File[]
-): SubmissionResult<'monolithic'> => {
+): MonolithicInstancePayload => {
 	const data = InstanceSubmissionData.from(instanceFile, attachments);
 
 	return {
@@ -110,17 +109,17 @@ const monolithicSubmissionResult = (
 	};
 };
 
-interface ChunkedSubmissionResultOptions {
+interface ChunkedInstancePayloadOptions {
 	readonly maxSize: number;
 }
 
-const chunkedSubmissionResult = (
+const chunkedInstancePayload = (
 	validation: SubmissionInstanceStateValidation,
 	definition: SubmissionDefinition,
 	instanceFile: InstanceFile,
 	attachments: readonly File[],
-	options: ChunkedSubmissionResultOptions
-): SubmissionResult<'chunked'> => {
+	options: ChunkedInstancePayloadOptions
+): ChunkedInstancePayload => {
 	if (attachments.length > 0 || options.maxSize !== Infinity) {
 		throw new Error('Submission chunking pending implementation');
 	}
@@ -134,39 +133,39 @@ const chunkedSubmissionResult = (
 	};
 };
 
-export interface PrepareSubmissionOptions<ChunkedType extends SubmissionChunkedType> {
-	readonly chunked: ChunkedType;
+export interface PrepareSubmissionOptions<PayloadType extends InstancePayloadType> {
+	readonly payloadType: PayloadType;
 	readonly maxSize: number;
 }
 
-export const prepareSubmission = <ChunkedType extends SubmissionChunkedType>(
+export const prepareSubmission = <PayloadType extends InstancePayloadType>(
 	instanceRoot: ClientReactiveSubmittableInstance,
-	options: PrepareSubmissionOptions<ChunkedType>
-): SubmissionResult<ChunkedType> => {
+	options: PrepareSubmissionOptions<PayloadType>
+): InstancePayload<PayloadType> => {
 	const validation = validateSubmission(instanceRoot);
 	const definition = instanceRoot.definition.submission;
 	const instanceFile = new InstanceFile(instanceRoot);
 	const attachments: readonly File[] = [];
 
-	switch (options.chunked) {
+	switch (options.payloadType) {
 		case 'chunked':
-			return chunkedSubmissionResult(
+			return chunkedInstancePayload(
 				validation,
 				definition,
 				instanceFile,
 				attachments,
 				options
-			) satisfies SubmissionResult<'chunked'> as SubmissionResult<ChunkedType>;
+			) satisfies ChunkedInstancePayload as InstancePayload<PayloadType>;
 
 		case 'monolithic':
-			return monolithicSubmissionResult(
+			return monolithicInstancePayload(
 				validation,
 				definition,
 				instanceFile,
 				attachments
-			) satisfies SubmissionResult<'monolithic'> as SubmissionResult<ChunkedType>;
+			) satisfies MonolithicInstancePayload as InstancePayload<PayloadType>;
 
 		default:
-			throw new UnreachableError(options.chunked);
+			throw new UnreachableError(options.payloadType);
 	}
 };

From 045ec3c2cc6fb46aefb597fdac4fc70d82de4438 Mon Sep 17 00:00:00 2001
From: eyelidlessness <gnosis@gmail.com>
Date: Wed, 26 Feb 2025 14:42:40 -0800
Subject: [PATCH 4/8] =?UTF-8?q?engine=20(internal):=20=E2=80=9Csubmission?=
 =?UTF-8?q?=E2=80=9D-related=20naming=20->=20=E2=80=9Cinstance=E2=80=9D=20?=
 =?UTF-8?q?as=20appropriate?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This commit will consolidate changes to engine internals, matching the same renaming effort for the engine/client interface.

- [x] `ClientReactiveSubmittable*` -> `ClientReactiveSerializable*`
- [x] `internal-api/submission` -> `internal-api/serialization`
- [x] `create*SubmissionState` -> `create*InstanceState`
- [x] `prepareSubmission` -> `prepareInstancePayload`
- [x] assorted comments
---
 packages/xforms-engine/src/instance/Group.ts  |  8 ++--
 .../src/instance/InputControl.ts              |  4 +-
 .../xforms-engine/src/instance/ModelValue.ts  |  4 +-
 packages/xforms-engine/src/instance/Note.ts   |  4 +-
 .../src/instance/PrimaryInstance.ts           | 14 +++---
 .../src/instance/RangeControl.ts              |  4 +-
 .../xforms-engine/src/instance/RankControl.ts | 18 ++++----
 packages/xforms-engine/src/instance/Root.ts   |  8 ++--
 .../src/instance/SelectControl.ts             |  4 +-
 .../xforms-engine/src/instance/Subtree.ts     |  8 ++--
 .../src/instance/TriggerControl.ts            |  4 +-
 .../instance/abstract/UnsupportedControl.ts   |  8 ++--
 .../src/instance/abstract/ValueNode.ts        |  8 ++--
 .../ClientReactiveSerializableInstance.ts     | 20 +++++++++
 .../ClientReactiveSerializableLeafNode.ts}    | 22 +++++-----
 .../ClientReactiveSerializableParentNode.ts   | 26 +++++++++++
 .../ClientReactiveSerializableValueNode.ts    | 28 ++++++++++++
 .../ClientReactiveSubmittableInstance.ts      | 20 ---------
 .../ClientReactiveSubmittableParentNode.ts    | 26 -----------
 .../ClientReactiveSubmittableValueNode.ts     | 28 ------------
 .../src/instance/repeat/BaseRepeatRange.ts    |  8 ++--
 .../src/instance/repeat/RepeatInstance.ts     |  8 ++--
 .../createLeafNodeInsstanceState.ts}          |  6 +--
 .../createNodeRangeInstanceState.ts}          |  6 +--
 .../createParentNodeInstanceState.ts}         |  6 +--
 .../createPrimaryInstanceState.ts             | 12 +++++
 .../createRootInstanceState.ts}               |  2 +-
 .../createValueNodeInstanceState.ts}          |  6 +--
 .../prepareInstancePayload.ts}                | 44 +++++++++----------
 .../createInstanceSubmissionState.ts          | 12 -----
 .../reactivity/createInstanceValueState.ts    |  2 +-
 .../src/lib/reactivity/createValueState.ts    |  4 +-
 32 files changed, 191 insertions(+), 191 deletions(-)
 create mode 100644 packages/xforms-engine/src/instance/internal-api/serialization/ClientReactiveSerializableInstance.ts
 rename packages/xforms-engine/src/instance/internal-api/{submission/ClientReactiveSubmittableLeafNode.ts => serialization/ClientReactiveSerializableLeafNode.ts} (60%)
 create mode 100644 packages/xforms-engine/src/instance/internal-api/serialization/ClientReactiveSerializableParentNode.ts
 create mode 100644 packages/xforms-engine/src/instance/internal-api/serialization/ClientReactiveSerializableValueNode.ts
 delete mode 100644 packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableInstance.ts
 delete mode 100644 packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableParentNode.ts
 delete mode 100644 packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableValueNode.ts
 rename packages/xforms-engine/src/lib/client-reactivity/{submission/createLeafNodeSubmissionState.ts => instance-state/createLeafNodeInsstanceState.ts} (66%)
 rename packages/xforms-engine/src/lib/client-reactivity/{submission/createNodeRangeSubmissionState.ts => instance-state/createNodeRangeInstanceState.ts} (61%)
 rename packages/xforms-engine/src/lib/client-reactivity/{submission/createParentNodeSubmissionState.ts => instance-state/createParentNodeInstanceState.ts} (69%)
 create mode 100644 packages/xforms-engine/src/lib/client-reactivity/instance-state/createPrimaryInstanceState.ts
 rename packages/xforms-engine/src/lib/client-reactivity/{submission/createRootSubmissionState.ts => instance-state/createRootInstanceState.ts} (89%)
 rename packages/xforms-engine/src/lib/client-reactivity/{submission/createValueNodeSubmissionState.ts => instance-state/createValueNodeInstanceState.ts} (66%)
 rename packages/xforms-engine/src/lib/client-reactivity/{submission/prepareSubmission.ts => instance-state/prepareInstancePayload.ts} (72%)
 delete mode 100644 packages/xforms-engine/src/lib/client-reactivity/submission/createInstanceSubmissionState.ts

diff --git a/packages/xforms-engine/src/instance/Group.ts b/packages/xforms-engine/src/instance/Group.ts
index b2729a70..d42fb648 100644
--- a/packages/xforms-engine/src/instance/Group.ts
+++ b/packages/xforms-engine/src/instance/Group.ts
@@ -6,7 +6,7 @@ import type { InstanceState } from '../client/serialization/InstanceState.ts';
 import type { TextRange } from '../client/TextRange.ts';
 import type { AncestorNodeValidationState } from '../client/validation.ts';
 import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
-import { createParentNodeSubmissionState } from '../lib/client-reactivity/submission/createParentNodeSubmissionState.ts';
+import { createParentNodeInstanceState } from '../lib/client-reactivity/instance-state/createParentNodeInstanceState.ts';
 import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -22,7 +22,7 @@ import { DescendantNode } from './abstract/DescendantNode.ts';
 import { buildChildren } from './children.ts';
 import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import type { ClientReactiveSubmittableParentNode } from './internal-api/submission/ClientReactiveSubmittableParentNode.ts';
+import type { ClientReactiveSerializableParentNode } from './internal-api/serialization/ClientReactiveSerializableParentNode.ts';
 
 // prettier-ignore
 interface GroupStateSpec extends DescendantNodeSharedStateSpec {
@@ -39,7 +39,7 @@ export class Group
 		GroupNode,
 		XFormsXPathElement,
 		EvaluationContext,
-		ClientReactiveSubmittableParentNode<GeneralChildNode>
+		ClientReactiveSerializableParentNode<GeneralChildNode>
 {
 	private readonly childrenState: ChildrenState<GeneralChildNode>;
 
@@ -97,7 +97,7 @@ export class Group
 
 		childrenState.setChildren(buildChildren(this));
 		this.validationState = createAggregatedViolations(this, sharedStateOptions);
-		this.instanceState = createParentNodeSubmissionState(this);
+		this.instanceState = createParentNodeInstanceState(this);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {
diff --git a/packages/xforms-engine/src/instance/InputControl.ts b/packages/xforms-engine/src/instance/InputControl.ts
index 84ab254f..ec694ae3 100644
--- a/packages/xforms-engine/src/instance/InputControl.ts
+++ b/packages/xforms-engine/src/instance/InputControl.ts
@@ -22,7 +22,7 @@ import type { InputControlDefinition } from '../parse/body/control/InputControlD
 import { ValueNode, type ValueNodeStateSpec } from './abstract/ValueNode.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import type { ClientReactiveSubmittableValueNode } from './internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import type { ClientReactiveSerializableValueNode } from './internal-api/serialization/ClientReactiveSerializableValueNode.ts';
 import type { ValidationContext } from './internal-api/ValidationContext.ts';
 import type { Root } from './Root.ts';
 
@@ -78,7 +78,7 @@ export class InputControl<V extends ValueType = ValueType>
 		XFormsXPathElement,
 		EvaluationContext,
 		ValidationContext,
-		ClientReactiveSubmittableValueNode
+		ClientReactiveSerializableValueNode
 {
 	static from(parent: GeneralParentNode, definition: InputDefinition): AnyInputControl;
 	static from<V extends ValueType>(
diff --git a/packages/xforms-engine/src/instance/ModelValue.ts b/packages/xforms-engine/src/instance/ModelValue.ts
index e9e5cc20..9b07a92e 100644
--- a/packages/xforms-engine/src/instance/ModelValue.ts
+++ b/packages/xforms-engine/src/instance/ModelValue.ts
@@ -12,7 +12,7 @@ import { ValueNode, type ValueNodeStateSpec } from './abstract/ValueNode.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
 import type { ValidationContext } from './internal-api/ValidationContext.ts';
-import type { ClientReactiveSubmittableValueNode } from './internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import type { ClientReactiveSerializableValueNode } from './internal-api/serialization/ClientReactiveSerializableValueNode.ts';
 
 interface ModelValueStateSpec<V extends ValueType> extends ValueNodeStateSpec<RuntimeValue<V>> {
 	readonly label: null;
@@ -27,7 +27,7 @@ export class ModelValue<V extends ValueType = ValueType>
 		XFormsXPathElement,
 		EvaluationContext,
 		ValidationContext,
-		ClientReactiveSubmittableValueNode
+		ClientReactiveSerializableValueNode
 {
 	static from(parent: GeneralParentNode, definition: ModelValueDefinition): AnyModelValue;
 	static from<V extends ValueType>(
diff --git a/packages/xforms-engine/src/instance/Note.ts b/packages/xforms-engine/src/instance/Note.ts
index 90d13eeb..a1d17921 100644
--- a/packages/xforms-engine/src/instance/Note.ts
+++ b/packages/xforms-engine/src/instance/Note.ts
@@ -19,7 +19,7 @@ import type { NoteNodeDefinition } from '../parse/model/NoteNodeDefinition.ts';
 import { ValueNode, type ValueNodeStateSpec } from './abstract/ValueNode.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import type { ClientReactiveSubmittableValueNode } from './internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import type { ClientReactiveSerializableValueNode } from './internal-api/serialization/ClientReactiveSerializableValueNode.ts';
 import type { ValidationContext } from './internal-api/ValidationContext.ts';
 
 interface NoteStateSpec<V extends ValueType> extends ValueNodeStateSpec<NoteValue<V>> {
@@ -37,7 +37,7 @@ export class Note<V extends ValueType = ValueType>
 		XFormsXPathElement,
 		EvaluationContext,
 		ValidationContext,
-		ClientReactiveSubmittableValueNode
+		ClientReactiveSerializableValueNode
 {
 	// XFormsXPathElement
 	override readonly [XPathNodeKindKey] = 'element';
diff --git a/packages/xforms-engine/src/instance/PrimaryInstance.ts b/packages/xforms-engine/src/instance/PrimaryInstance.ts
index ebb41479..d61f125f 100644
--- a/packages/xforms-engine/src/instance/PrimaryInstance.ts
+++ b/packages/xforms-engine/src/instance/PrimaryInstance.ts
@@ -13,8 +13,8 @@ import type { InstanceState } from '../client/serialization/InstanceState.ts';
 import type { AncestorNodeValidationState } from '../client/validation.ts';
 import type { XFormsXPathDocument } from '../integration/xpath/adapter/XFormsXPathNode.ts';
 import { EngineXPathEvaluator } from '../integration/xpath/EngineXPathEvaluator.ts';
-import { createInstanceSubmissionState } from '../lib/client-reactivity/submission/createInstanceSubmissionState.ts';
-import { prepareSubmission } from '../lib/client-reactivity/submission/prepareSubmission.ts';
+import { createPrimaryInstanceState } from '../lib/client-reactivity/instance-state/createPrimaryInstanceState.ts';
+import { prepareInstancePayload } from '../lib/client-reactivity/instance-state/prepareInstancePayload.ts';
 import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import { createTranslationState } from '../lib/reactivity/createTranslationState.ts';
 import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -33,7 +33,7 @@ import { InstanceNode } from './abstract/InstanceNode.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
 import type { InstanceConfig } from './internal-api/InstanceConfig.ts';
 import type { PrimaryInstanceDocument } from './internal-api/PrimaryInstanceDocument.ts';
-import type { ClientReactiveSubmittableInstance } from './internal-api/submission/ClientReactiveSubmittableInstance.ts';
+import type { ClientReactiveSerializableInstance } from './internal-api/serialization/ClientReactiveSerializableInstance.ts';
 import type { TranslationContext } from './internal-api/TranslationContext.ts';
 import { Root } from './Root.ts';
 
@@ -81,7 +81,7 @@ export class PrimaryInstance
 		XFormsXPathDocument,
 		TranslationContext,
 		EvaluationContext,
-		ClientReactiveSubmittableInstance
+		ClientReactiveSerializableInstance
 {
 	// InstanceNode
 	protected readonly state: SharedNodeState<PrimaryInstanceStateSpec>;
@@ -99,7 +99,7 @@ export class PrimaryInstance
 	// XFormsXPathDocument
 	readonly [XPathNodeKindKey] = 'document';
 
-	// PrimaryInstanceDocument, ClientReactiveSubmittableInstance
+	// PrimaryInstanceDocument, ClientReactiveSerializableInstance
 	readonly nodeType = 'primary-instance';
 	readonly appearances = null;
 	readonly nodeOptions = null;
@@ -187,7 +187,7 @@ export class PrimaryInstance
 				return root.validationState.violations;
 			},
 		};
-		this.instanceState = createInstanceSubmissionState(this);
+		this.instanceState = createPrimaryInstanceState(this);
 
 		childrenState.setChildren([root]);
 		setIsAttached(true);
@@ -235,7 +235,7 @@ export class PrimaryInstance
 	prepareInstancePayload<PayloadType extends InstancePayloadType = 'monolithic'>(
 		options?: InstancePayloadOptions<PayloadType>
 	): Promise<InstancePayload<PayloadType>> {
-		const result = prepareSubmission(this, {
+		const result = prepareInstancePayload(this, {
 			payloadType: (options?.payloadType ?? 'monolithic') as PayloadType,
 			maxSize: options?.maxSize ?? Infinity,
 		});
diff --git a/packages/xforms-engine/src/instance/RangeControl.ts b/packages/xforms-engine/src/instance/RangeControl.ts
index f00c9208..817a1731 100644
--- a/packages/xforms-engine/src/instance/RangeControl.ts
+++ b/packages/xforms-engine/src/instance/RangeControl.ts
@@ -26,7 +26,7 @@ import { ValueNode, type ValueNodeStateSpec } from './abstract/ValueNode.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
 import type { ValidationContext } from './internal-api/ValidationContext.ts';
-import type { ClientReactiveSubmittableValueNode } from './internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import type { ClientReactiveSerializableValueNode } from './internal-api/serialization/ClientReactiveSerializableValueNode.ts';
 
 interface RangeControlStateSpec<V extends RangeValueType>
 	extends ValueNodeStateSpec<RangeValue<V>> {
@@ -42,7 +42,7 @@ export class RangeControl<V extends RangeValueType = RangeValueType>
 		XFormsXPathElement,
 		EvaluationContext,
 		ValidationContext,
-		ClientReactiveSubmittableValueNode
+		ClientReactiveSerializableValueNode
 {
 	static from(parent: GeneralParentNode, definition: AnyRangeNodeDefinition): AnyRangeControl;
 	static from<V extends RangeValueType>(
diff --git a/packages/xforms-engine/src/instance/RankControl.ts b/packages/xforms-engine/src/instance/RankControl.ts
index 73d40f68..306fa517 100644
--- a/packages/xforms-engine/src/instance/RankControl.ts
+++ b/packages/xforms-engine/src/instance/RankControl.ts
@@ -3,7 +3,13 @@ import type { Accessor } from 'solid-js';
 import { createMemo } from 'solid-js';
 import type { RankDefinition, RankItem, RankNode, RankValueOptions } from '../client/RankNode.ts';
 import type { TextRange } from '../client/TextRange.ts';
+import type { ValueType } from '../client/ValueType.ts';
+import { RankMissingValueError } from '../error/RankMissingValueError.ts';
+import { RankValueTypeError } from '../error/RankValueTypeError.ts';
 import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
+import { sharedValueCodecs } from '../lib/codecs/getSharedValueCodec.ts';
+import { MultipleValueItemCodec } from '../lib/codecs/items/MultipleValueItemCodec.ts';
+import { createItemCollection } from '../lib/reactivity/createItemCollection.ts';
 import type { CurrentState } from '../lib/reactivity/node-state/createCurrentState.ts';
 import type { EngineState } from '../lib/reactivity/node-state/createEngineState.ts';
 import type { SharedNodeState } from '../lib/reactivity/node-state/createSharedNodeState.ts';
@@ -11,20 +17,14 @@ import { createSharedNodeState } from '../lib/reactivity/node-state/createShared
 import { createFieldHint } from '../lib/reactivity/text/createFieldHint.ts';
 import { createNodeLabel } from '../lib/reactivity/text/createNodeLabel.ts';
 import type { SimpleAtomicState } from '../lib/reactivity/types.ts';
+import type { UnknownAppearanceDefinition } from '../parse/body/appearance/unknownAppearanceParser.ts';
 import type { Root } from './Root.ts';
 import type { ValueNodeStateSpec } from './abstract/ValueNode.ts';
 import { ValueNode } from './abstract/ValueNode.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
 import type { ValidationContext } from './internal-api/ValidationContext.ts';
-import type { ClientReactiveSubmittableValueNode } from './internal-api/submission/ClientReactiveSubmittableValueNode.ts';
-import { MultipleValueItemCodec } from '../lib/codecs/items/MultipleValueItemCodec.ts';
-import { sharedValueCodecs } from '../lib/codecs/getSharedValueCodec.ts';
-import { createItemCollection } from '../lib/reactivity/createItemCollection.ts';
-import type { UnknownAppearanceDefinition } from '../parse/body/appearance/unknownAppearanceParser.ts';
-import type { ValueType } from '../client/ValueType.ts';
-import { RankMissingValueError } from '../error/RankMissingValueError.ts';
-import { RankValueTypeError } from '../error/RankValueTypeError.ts';
+import type { ClientReactiveSerializableValueNode } from './internal-api/serialization/ClientReactiveSerializableValueNode.ts';
 
 export type AnyRankDefinition = {
 	[V in ValueType]: RankDefinition<V>;
@@ -66,7 +66,7 @@ export class RankControl
 		XFormsXPathElement,
 		EvaluationContext,
 		ValidationContext,
-		ClientReactiveSubmittableValueNode
+		ClientReactiveSerializableValueNode
 {
 	static from(parent: GeneralParentNode, definition: RankDefinition): RankControl;
 	static from(parent: GeneralParentNode, definition: AnyRankDefinition): RankControl {
diff --git a/packages/xforms-engine/src/instance/Root.ts b/packages/xforms-engine/src/instance/Root.ts
index 36fe4a68..01d96fc0 100644
--- a/packages/xforms-engine/src/instance/Root.ts
+++ b/packages/xforms-engine/src/instance/Root.ts
@@ -11,7 +11,7 @@ import type {
 import type { InstanceState } from '../client/serialization/InstanceState.ts';
 import type { AncestorNodeValidationState } from '../client/validation.ts';
 import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
-import { createRootSubmissionState } from '../lib/client-reactivity/submission/createRootSubmissionState.ts';
+import { createRootInstanceState } from '../lib/client-reactivity/instance-state/createRootInstanceState.ts';
 import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -27,7 +27,7 @@ import { DescendantNode } from './abstract/DescendantNode.ts';
 import { buildChildren } from './children.ts';
 import type { GeneralChildNode } from './hierarchy.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import type { ClientReactiveSubmittableParentNode } from './internal-api/submission/ClientReactiveSubmittableParentNode.ts';
+import type { ClientReactiveSerializableParentNode } from './internal-api/serialization/ClientReactiveSerializableParentNode.ts';
 import type { TranslationContext } from './internal-api/TranslationContext.ts';
 import type { PrimaryInstance } from './PrimaryInstance.ts';
 
@@ -53,7 +53,7 @@ export class Root
 		XFormsXPathElement,
 		EvaluationContext,
 		TranslationContext,
-		ClientReactiveSubmittableParentNode<GeneralChildNode>
+		ClientReactiveSerializableParentNode<GeneralChildNode>
 {
 	private readonly childrenState: ChildrenState<GeneralChildNode>;
 
@@ -129,7 +129,7 @@ export class Root
 
 		childrenState.setChildren(buildChildren(this));
 		this.validationState = createAggregatedViolations(this, sharedStateOptions);
-		this.instanceState = createRootSubmissionState(this);
+		this.instanceState = createRootInstanceState(this);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {
diff --git a/packages/xforms-engine/src/instance/SelectControl.ts b/packages/xforms-engine/src/instance/SelectControl.ts
index 5592c2bb..e4a4ba51 100644
--- a/packages/xforms-engine/src/instance/SelectControl.ts
+++ b/packages/xforms-engine/src/instance/SelectControl.ts
@@ -28,7 +28,7 @@ import { ValueNode } from './abstract/ValueNode.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
 import type { ValidationContext } from './internal-api/ValidationContext.ts';
-import type { ClientReactiveSubmittableValueNode } from './internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import type { ClientReactiveSerializableValueNode } from './internal-api/serialization/ClientReactiveSerializableValueNode.ts';
 
 export type AnySelectDefinition = {
 	[V in ValueType]: SelectDefinition<V>;
@@ -59,7 +59,7 @@ export class SelectControl
 		XFormsXPathElement,
 		EvaluationContext,
 		ValidationContext,
-		ClientReactiveSubmittableValueNode
+		ClientReactiveSerializableValueNode
 {
 	static from(parent: GeneralParentNode, definition: SelectDefinition): SelectControl;
 	static from(parent: GeneralParentNode, definition: AnySelectDefinition): SelectControl {
diff --git a/packages/xforms-engine/src/instance/Subtree.ts b/packages/xforms-engine/src/instance/Subtree.ts
index 92ed4991..ddc7f902 100644
--- a/packages/xforms-engine/src/instance/Subtree.ts
+++ b/packages/xforms-engine/src/instance/Subtree.ts
@@ -5,7 +5,7 @@ import type { InstanceState } from '../client/serialization/InstanceState.ts';
 import type { SubtreeDefinition, SubtreeNode } from '../client/SubtreeNode.ts';
 import type { AncestorNodeValidationState } from '../client/validation.ts';
 import type { XFormsXPathElement } from '../integration/xpath/adapter/XFormsXPathNode.ts';
-import { createParentNodeSubmissionState } from '../lib/client-reactivity/submission/createParentNodeSubmissionState.ts';
+import { createParentNodeInstanceState } from '../lib/client-reactivity/instance-state/createParentNodeInstanceState.ts';
 import type { ChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -20,7 +20,7 @@ import { DescendantNode } from './abstract/DescendantNode.ts';
 import { buildChildren } from './children.ts';
 import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
-import type { ClientReactiveSubmittableParentNode } from './internal-api/submission/ClientReactiveSubmittableParentNode.ts';
+import type { ClientReactiveSerializableParentNode } from './internal-api/serialization/ClientReactiveSerializableParentNode.ts';
 
 interface SubtreeStateSpec extends DescendantNodeSharedStateSpec {
 	readonly label: null;
@@ -36,7 +36,7 @@ export class Subtree
 		SubtreeNode,
 		XFormsXPathElement,
 		EvaluationContext,
-		ClientReactiveSubmittableParentNode<GeneralChildNode>
+		ClientReactiveSerializableParentNode<GeneralChildNode>
 {
 	private readonly childrenState: ChildrenState<GeneralChildNode>;
 
@@ -92,7 +92,7 @@ export class Subtree
 
 		childrenState.setChildren(buildChildren(this));
 		this.validationState = createAggregatedViolations(this, sharedStateOptions);
-		this.instanceState = createParentNodeSubmissionState(this);
+		this.instanceState = createParentNodeInstanceState(this);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {
diff --git a/packages/xforms-engine/src/instance/TriggerControl.ts b/packages/xforms-engine/src/instance/TriggerControl.ts
index 36c0fa7a..333c5290 100644
--- a/packages/xforms-engine/src/instance/TriggerControl.ts
+++ b/packages/xforms-engine/src/instance/TriggerControl.ts
@@ -19,7 +19,7 @@ import { ValueNode, type ValueNodeStateSpec } from './abstract/ValueNode.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { EvaluationContext } from './internal-api/EvaluationContext.ts';
 import type { ValidationContext } from './internal-api/ValidationContext.ts';
-import type { ClientReactiveSubmittableValueNode } from './internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import type { ClientReactiveSerializableValueNode } from './internal-api/serialization/ClientReactiveSerializableValueNode.ts';
 
 interface TriggerControlStateSpec extends ValueNodeStateSpec<TriggerRuntimeValue> {
 	readonly label: Accessor<TextRange<'label'> | null>;
@@ -45,7 +45,7 @@ export class TriggerControl
 		XFormsXPathElement,
 		EvaluationContext,
 		ValidationContext,
-		ClientReactiveSubmittableValueNode
+		ClientReactiveSerializableValueNode
 {
 	static from(parent: GeneralParentNode, definition: TriggerNodeDefinition): TriggerControl;
 	static from(parent: GeneralParentNode, definition: AnyTriggerNodeDefinition): TriggerControl {
diff --git a/packages/xforms-engine/src/instance/abstract/UnsupportedControl.ts b/packages/xforms-engine/src/instance/abstract/UnsupportedControl.ts
index 6ff87c15..dd61fc37 100644
--- a/packages/xforms-engine/src/instance/abstract/UnsupportedControl.ts
+++ b/packages/xforms-engine/src/instance/abstract/UnsupportedControl.ts
@@ -11,7 +11,7 @@ import type {
 } from '../../client/unsupported/UnsupportedControlNode.ts';
 import type { AnyViolation, LeafNodeValidationState } from '../../client/validation.ts';
 import type { XFormsXPathElement } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
-import { createLeafNodeSubmissionState } from '../../lib/client-reactivity/submission/createLeafNodeSubmissionState.ts';
+import { createLeafNodeInsstanceState } from '../../lib/client-reactivity/instance-state/createLeafNodeInsstanceState.ts';
 import { createValueState } from '../../lib/reactivity/createValueState.ts';
 import type { CurrentState } from '../../lib/reactivity/node-state/createCurrentState.ts';
 import type { EngineState } from '../../lib/reactivity/node-state/createEngineState.ts';
@@ -29,7 +29,7 @@ import {
 import type { UnknownAppearanceDefinition } from '../../parse/body/appearance/unknownAppearanceParser.ts';
 import type { AnyUnsupportedControl, GeneralParentNode } from '../hierarchy.ts';
 import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
-import type { ClientReactiveSubmittableLeafNode } from '../internal-api/submission/ClientReactiveSubmittableLeafNode.ts';
+import type { ClientReactiveSerializableLeafNode } from '../internal-api/serialization/ClientReactiveSerializableLeafNode.ts';
 import type { ValidationContext } from '../internal-api/ValidationContext.ts';
 import type { ValueContext } from '../internal-api/ValueContext.ts';
 import { DescendantNode, type DescendantNodeStateSpec } from './DescendantNode.ts';
@@ -77,7 +77,7 @@ export abstract class UnsupportedControl<Type extends UnsupportedControlNodeType
 		EvaluationContext,
 		ValidationContext,
 		ValueContext<unknown>,
-		ClientReactiveSubmittableLeafNode<unknown>
+		ClientReactiveSerializableLeafNode<unknown>
 {
 	private readonly validation: SharedValidationState;
 	protected readonly state: SharedNodeState<UnsupportedControlStateSpec>;
@@ -146,7 +146,7 @@ export abstract class UnsupportedControl<Type extends UnsupportedControlNodeType
 		this.engineState = state.engineState;
 		this.currentState = state.currentState;
 		this.validation = createValidationState(this, sharedStateOptions);
-		this.instanceState = createLeafNodeSubmissionState(this);
+		this.instanceState = createLeafNodeInsstanceState(this);
 	}
 
 	// XFormsXPathElement
diff --git a/packages/xforms-engine/src/instance/abstract/ValueNode.ts b/packages/xforms-engine/src/instance/abstract/ValueNode.ts
index bb5ec3ef..300d1ff1 100644
--- a/packages/xforms-engine/src/instance/abstract/ValueNode.ts
+++ b/packages/xforms-engine/src/instance/abstract/ValueNode.ts
@@ -6,7 +6,7 @@ import type { InstanceState } from '../../client/serialization/InstanceState.ts'
 import type { AnyViolation, LeafNodeValidationState } from '../../client/validation.ts';
 import type { ValueType } from '../../client/ValueType.ts';
 import type { XFormsXPathElement } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
-import { createValueNodeSubmissionState } from '../../lib/client-reactivity/submission/createValueNodeSubmissionState.ts';
+import { createValueNodeInstanceState } from '../../lib/client-reactivity/instance-state/createValueNodeInstanceState.ts';
 import type {
 	RuntimeValueSetter,
 	RuntimeValueState,
@@ -26,7 +26,7 @@ import type {
 	DecodeInstanceValue,
 	InstanceValueContext,
 } from '../internal-api/InstanceValueContext.ts';
-import type { ClientReactiveSubmittableValueNode } from '../internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import type { ClientReactiveSerializableValueNode } from '../internal-api/serialization/ClientReactiveSerializableValueNode.ts';
 import type { ValidationContext } from '../internal-api/ValidationContext.ts';
 import type { DescendantNodeStateSpec } from './DescendantNode.ts';
 import { DescendantNode } from './DescendantNode.ts';
@@ -52,7 +52,7 @@ export abstract class ValueNode<
 		EvaluationContext,
 		InstanceValueContext,
 		ValidationContext,
-		ClientReactiveSubmittableValueNode
+		ClientReactiveSerializableValueNode
 {
 	protected readonly validation: SharedValidationState;
 	protected readonly getInstanceValue: Accessor<string>;
@@ -109,7 +109,7 @@ export abstract class ValueNode<
 		this.validation = createValidationState(this, {
 			clientStateFactory: this.engineConfig.stateFactory,
 		});
-		this.instanceState = createValueNodeSubmissionState(this);
+		this.instanceState = createValueNodeInstanceState(this);
 	}
 
 	// ValidationContext
diff --git a/packages/xforms-engine/src/instance/internal-api/serialization/ClientReactiveSerializableInstance.ts b/packages/xforms-engine/src/instance/internal-api/serialization/ClientReactiveSerializableInstance.ts
new file mode 100644
index 00000000..1fde0a8e
--- /dev/null
+++ b/packages/xforms-engine/src/instance/internal-api/serialization/ClientReactiveSerializableInstance.ts
@@ -0,0 +1,20 @@
+import type { SubmissionDefinition } from '../../../client/submission/SubmissionDefinition.ts';
+import type { AncestorNodeValidationState } from '../../../client/validation.ts';
+import type { Root } from '../../Root.ts';
+import type {
+	ClientReactiveSerializableParentNode,
+	ClientReactiveSerializableParentNodeDefinition,
+} from './ClientReactiveSerializableParentNode.ts';
+
+interface ClientReactiveSerializableInstanceDefinition
+	extends ClientReactiveSerializableParentNodeDefinition {
+	readonly submission: SubmissionDefinition;
+}
+
+export interface ClientReactiveSerializableInstance
+	extends ClientReactiveSerializableParentNode<Root> {
+	readonly definition: ClientReactiveSerializableInstanceDefinition;
+	readonly root: Root;
+	readonly parent: null;
+	readonly validationState: AncestorNodeValidationState;
+}
diff --git a/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableLeafNode.ts b/packages/xforms-engine/src/instance/internal-api/serialization/ClientReactiveSerializableLeafNode.ts
similarity index 60%
rename from packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableLeafNode.ts
rename to packages/xforms-engine/src/instance/internal-api/serialization/ClientReactiveSerializableLeafNode.ts
index 362ed7d2..11bae059 100644
--- a/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableLeafNode.ts
+++ b/packages/xforms-engine/src/instance/internal-api/serialization/ClientReactiveSerializableLeafNode.ts
@@ -2,28 +2,28 @@ import type { InstanceState } from '../../../client/serialization/InstanceState.
 import type { QualifiedName } from '../../../lib/names/QualifiedName.ts';
 import type { EscapedXMLText } from '../../../lib/xml-serialization.ts';
 import type {
-	ClientReactiveSubmittableChildNode,
-	ClientReactiveSubmittableParentNode,
-} from './ClientReactiveSubmittableParentNode.ts';
+	ClientReactiveSerializableChildNode,
+	ClientReactiveSerializableParentNode,
+} from './ClientReactiveSerializableParentNode.ts';
 
-interface ClientReactiveSubmittableLeafNodeCurrentState<RuntimeValue> {
+interface ClientReactiveSerializableLeafNodeCurrentState<RuntimeValue> {
 	get relevant(): boolean;
 	get value(): RuntimeValue;
 }
 
-export type SerializedSubmissionValue = string;
+export type SerializedInstanceValue = string;
 
-interface ClientReactiveSubmittableLeafNodeDefinition {
+interface ClientReactiveSerializableLeafNodeDefinition {
 	readonly qualifiedName: QualifiedName;
 }
 
-export interface ClientReactiveSubmittableLeafNode<RuntimeValue> {
-	readonly definition: ClientReactiveSubmittableLeafNodeDefinition;
-	readonly parent: ClientReactiveSubmittableParentNode<ClientReactiveSubmittableChildNode>;
-	readonly currentState: ClientReactiveSubmittableLeafNodeCurrentState<RuntimeValue>;
+export interface ClientReactiveSerializableLeafNode<RuntimeValue> {
+	readonly definition: ClientReactiveSerializableLeafNodeDefinition;
+	readonly parent: ClientReactiveSerializableParentNode<ClientReactiveSerializableChildNode>;
+	readonly currentState: ClientReactiveSerializableLeafNodeCurrentState<RuntimeValue>;
 
 	/**
-	 * A client-reactive submittable leaf node is responsible for producing a
+	 * A client-reactive serializble leaf node is responsible for producing a
 	 * string representation of its value state, suitable for instance
 	 * serialization. It **MUST NOT** perform any further instance
 	 * serialization-specific serialization duties: in particular, the value
diff --git a/packages/xforms-engine/src/instance/internal-api/serialization/ClientReactiveSerializableParentNode.ts b/packages/xforms-engine/src/instance/internal-api/serialization/ClientReactiveSerializableParentNode.ts
new file mode 100644
index 00000000..76bf43af
--- /dev/null
+++ b/packages/xforms-engine/src/instance/internal-api/serialization/ClientReactiveSerializableParentNode.ts
@@ -0,0 +1,26 @@
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import type { QualifiedName } from '../../../lib/names/QualifiedName.ts';
+
+export interface ClientReactiveSerializableChildNode {
+	readonly instanceState: InstanceState;
+}
+
+interface ClientReactiveSerializableParentNodeCurrentState<
+	Child extends ClientReactiveSerializableChildNode,
+> {
+	get relevant(): boolean;
+	get children(): readonly Child[];
+}
+
+export interface ClientReactiveSerializableParentNodeDefinition {
+	readonly qualifiedName: QualifiedName;
+}
+
+export interface ClientReactiveSerializableParentNode<
+	Child extends ClientReactiveSerializableChildNode,
+> {
+	readonly definition: ClientReactiveSerializableParentNodeDefinition;
+	readonly parent: ClientReactiveSerializableParentNode<ClientReactiveSerializableChildNode> | null;
+	readonly currentState: ClientReactiveSerializableParentNodeCurrentState<Child>;
+	readonly instanceState: InstanceState;
+}
diff --git a/packages/xforms-engine/src/instance/internal-api/serialization/ClientReactiveSerializableValueNode.ts b/packages/xforms-engine/src/instance/internal-api/serialization/ClientReactiveSerializableValueNode.ts
new file mode 100644
index 00000000..ffb1c378
--- /dev/null
+++ b/packages/xforms-engine/src/instance/internal-api/serialization/ClientReactiveSerializableValueNode.ts
@@ -0,0 +1,28 @@
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import type { QualifiedName } from '../../../lib/names/QualifiedName.ts';
+import type {
+	ClientReactiveSerializableChildNode,
+	ClientReactiveSerializableParentNode,
+} from './ClientReactiveSerializableParentNode.ts';
+
+export type SerializedInstanceValue = string;
+
+interface ClientReactiveSerializableValueNodeCurrentState {
+	get relevant(): boolean;
+
+	/**
+	 * @todo Consider moving into {@link InstanceState}
+	 */
+	get instanceValue(): SerializedInstanceValue;
+}
+
+interface ClientReactiveSerializableValueNodeDefinition {
+	readonly qualifiedName: QualifiedName;
+}
+
+export interface ClientReactiveSerializableValueNode {
+	readonly definition: ClientReactiveSerializableValueNodeDefinition;
+	readonly parent: ClientReactiveSerializableParentNode<ClientReactiveSerializableChildNode>;
+	readonly currentState: ClientReactiveSerializableValueNodeCurrentState;
+	readonly instanceState: InstanceState;
+}
diff --git a/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableInstance.ts b/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableInstance.ts
deleted file mode 100644
index 71455705..00000000
--- a/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableInstance.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import type { SubmissionDefinition } from '../../../client/submission/SubmissionDefinition.ts';
-import type { AncestorNodeValidationState } from '../../../client/validation.ts';
-import type { Root } from '../../Root.ts';
-import type {
-	ClientReactiveSubmittableParentNode,
-	ClientReactiveSubmittableParentNodeDefinition,
-} from './ClientReactiveSubmittableParentNode.ts';
-
-interface ClientReactiveSubmittableInstanceDefinition
-	extends ClientReactiveSubmittableParentNodeDefinition {
-	readonly submission: SubmissionDefinition;
-}
-
-export interface ClientReactiveSubmittableInstance
-	extends ClientReactiveSubmittableParentNode<Root> {
-	readonly definition: ClientReactiveSubmittableInstanceDefinition;
-	readonly root: Root;
-	readonly parent: null;
-	readonly validationState: AncestorNodeValidationState;
-}
diff --git a/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableParentNode.ts b/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableParentNode.ts
deleted file mode 100644
index 692556b4..00000000
--- a/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableParentNode.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
-import type { QualifiedName } from '../../../lib/names/QualifiedName.ts';
-
-export interface ClientReactiveSubmittableChildNode {
-	readonly instanceState: InstanceState;
-}
-
-interface ClientReactiveSubmittableParentNodeCurrentState<
-	Child extends ClientReactiveSubmittableChildNode,
-> {
-	get relevant(): boolean;
-	get children(): readonly Child[];
-}
-
-export interface ClientReactiveSubmittableParentNodeDefinition {
-	readonly qualifiedName: QualifiedName;
-}
-
-export interface ClientReactiveSubmittableParentNode<
-	Child extends ClientReactiveSubmittableChildNode,
-> {
-	readonly definition: ClientReactiveSubmittableParentNodeDefinition;
-	readonly parent: ClientReactiveSubmittableParentNode<ClientReactiveSubmittableChildNode> | null;
-	readonly currentState: ClientReactiveSubmittableParentNodeCurrentState<Child>;
-	readonly instanceState: InstanceState;
-}
diff --git a/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableValueNode.ts b/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableValueNode.ts
deleted file mode 100644
index ba924447..00000000
--- a/packages/xforms-engine/src/instance/internal-api/submission/ClientReactiveSubmittableValueNode.ts
+++ /dev/null
@@ -1,28 +0,0 @@
-import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
-import type { QualifiedName } from '../../../lib/names/QualifiedName.ts';
-import type {
-	ClientReactiveSubmittableChildNode,
-	ClientReactiveSubmittableParentNode,
-} from './ClientReactiveSubmittableParentNode.ts';
-
-interface ClientReactiveSubmittableValueNodeCurrentState {
-	get relevant(): boolean;
-
-	/**
-	 * @todo Consider moving into {@link InstanceState}
-	 */
-	get instanceValue(): string;
-}
-
-export type SerializedSubmissionValue = string;
-
-interface ClientReactiveSubmittableValueNodeDefinition {
-	readonly qualifiedName: QualifiedName;
-}
-
-export interface ClientReactiveSubmittableValueNode {
-	readonly definition: ClientReactiveSubmittableValueNodeDefinition;
-	readonly parent: ClientReactiveSubmittableParentNode<ClientReactiveSubmittableChildNode>;
-	readonly currentState: ClientReactiveSubmittableValueNodeCurrentState;
-	readonly instanceState: InstanceState;
-}
diff --git a/packages/xforms-engine/src/instance/repeat/BaseRepeatRange.ts b/packages/xforms-engine/src/instance/repeat/BaseRepeatRange.ts
index aaa71c3d..0f725ca1 100644
--- a/packages/xforms-engine/src/instance/repeat/BaseRepeatRange.ts
+++ b/packages/xforms-engine/src/instance/repeat/BaseRepeatRange.ts
@@ -14,7 +14,7 @@ import type {
 	XFormsXPathNodeRangeKind,
 } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import { XFORMS_XPATH_NODE_RANGE_KIND } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
-import { createNodeRangeSubmissionState } from '../../lib/client-reactivity/submission/createNodeRangeSubmissionState.ts';
+import { createNodeRangeInstanceState } from '../../lib/client-reactivity/instance-state/createNodeRangeInstanceState.ts';
 import type { ChildrenState } from '../../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -35,7 +35,7 @@ import type {
 import { DescendantNode } from '../abstract/DescendantNode.ts';
 import type { GeneralParentNode, RepeatRange } from '../hierarchy.ts';
 import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
-import type { ClientReactiveSubmittableParentNode } from '../internal-api/submission/ClientReactiveSubmittableParentNode.ts';
+import type { ClientReactiveSerializableParentNode } from '../internal-api/serialization/ClientReactiveSerializableParentNode.ts';
 import { RepeatInstance, type RepeatDefinition } from './RepeatInstance.ts';
 
 interface RepeatRangeStateSpec extends DescendantNodeSharedStateSpec {
@@ -58,7 +58,7 @@ export abstract class BaseRepeatRange<Definition extends AnyRepeatRangeDefinitio
 		BaseRepeatRangeNode,
 		XFormsXPathNodeRange,
 		EvaluationContext,
-		ClientReactiveSubmittableParentNode<RepeatInstance>
+		ClientReactiveSerializableParentNode<RepeatInstance>
 {
 	protected readonly childrenState: ChildrenState<RepeatInstance>;
 
@@ -188,7 +188,7 @@ export abstract class BaseRepeatRange<Definition extends AnyRepeatRangeDefinitio
 			state.currentState,
 			childrenState
 		);
-		this.instanceState = createNodeRangeSubmissionState(this);
+		this.instanceState = createNodeRangeInstanceState(this);
 	}
 
 	protected getLastIndex(): number {
diff --git a/packages/xforms-engine/src/instance/repeat/RepeatInstance.ts b/packages/xforms-engine/src/instance/repeat/RepeatInstance.ts
index 654110c7..55554086 100644
--- a/packages/xforms-engine/src/instance/repeat/RepeatInstance.ts
+++ b/packages/xforms-engine/src/instance/repeat/RepeatInstance.ts
@@ -11,7 +11,7 @@ import type { InstanceState } from '../../client/serialization/InstanceState.ts'
 import type { TextRange } from '../../client/TextRange.ts';
 import type { AncestorNodeValidationState } from '../../client/validation.ts';
 import type { XFormsXPathElement } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
-import { createParentNodeSubmissionState } from '../../lib/client-reactivity/submission/createParentNodeSubmissionState.ts';
+import { createParentNodeInstanceState } from '../../lib/client-reactivity/instance-state/createParentNodeInstanceState.ts';
 import type { ChildrenState } from '../../lib/reactivity/createChildrenState.ts';
 import { createChildrenState } from '../../lib/reactivity/createChildrenState.ts';
 import type { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
@@ -27,7 +27,7 @@ import { DescendantNode } from '../abstract/DescendantNode.ts';
 import { buildChildren } from '../children.ts';
 import type { GeneralChildNode, RepeatRange } from '../hierarchy.ts';
 import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
-import type { ClientReactiveSubmittableParentNode } from '../internal-api/submission/ClientReactiveSubmittableParentNode.ts';
+import type { ClientReactiveSerializableParentNode } from '../internal-api/serialization/ClientReactiveSerializableParentNode.ts';
 
 export type { RepeatDefinition };
 
@@ -49,7 +49,7 @@ export class RepeatInstance
 		RepeatInstanceNode,
 		XFormsXPathElement,
 		EvaluationContext,
-		ClientReactiveSubmittableParentNode<GeneralChildNode>
+		ClientReactiveSerializableParentNode<GeneralChildNode>
 {
 	private readonly childrenState: ChildrenState<GeneralChildNode>;
 	private readonly currentIndex: Accessor<number>;
@@ -179,7 +179,7 @@ export class RepeatInstance
 
 		childrenState.setChildren(buildChildren(this));
 		this.validationState = createAggregatedViolations(this, sharedStateOptions);
-		this.instanceState = createParentNodeSubmissionState(this);
+		this.instanceState = createParentNodeInstanceState(this);
 	}
 
 	getChildren(): readonly GeneralChildNode[] {
diff --git a/packages/xforms-engine/src/lib/client-reactivity/submission/createLeafNodeSubmissionState.ts b/packages/xforms-engine/src/lib/client-reactivity/instance-state/createLeafNodeInsstanceState.ts
similarity index 66%
rename from packages/xforms-engine/src/lib/client-reactivity/submission/createLeafNodeSubmissionState.ts
rename to packages/xforms-engine/src/lib/client-reactivity/instance-state/createLeafNodeInsstanceState.ts
index 39770a95..09ca685f 100644
--- a/packages/xforms-engine/src/lib/client-reactivity/submission/createLeafNodeSubmissionState.ts
+++ b/packages/xforms-engine/src/lib/client-reactivity/instance-state/createLeafNodeInsstanceState.ts
@@ -1,9 +1,9 @@
 import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
-import type { ClientReactiveSubmittableLeafNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableLeafNode.ts';
+import type { ClientReactiveSerializableLeafNode } from '../../../instance/internal-api/serialization/ClientReactiveSerializableLeafNode.ts';
 import { escapeXMLText, serializeLeafElementXML } from '../../xml-serialization.ts';
 
-export const createLeafNodeSubmissionState = <Value>(
-	node: ClientReactiveSubmittableLeafNode<Value>
+export const createLeafNodeInsstanceState = <Value>(
+	node: ClientReactiveSerializableLeafNode<Value>
 ): InstanceState => {
 	return {
 		get instanceXML() {
diff --git a/packages/xforms-engine/src/lib/client-reactivity/submission/createNodeRangeSubmissionState.ts b/packages/xforms-engine/src/lib/client-reactivity/instance-state/createNodeRangeInstanceState.ts
similarity index 61%
rename from packages/xforms-engine/src/lib/client-reactivity/submission/createNodeRangeSubmissionState.ts
rename to packages/xforms-engine/src/lib/client-reactivity/instance-state/createNodeRangeInstanceState.ts
index 4824407d..677cbe97 100644
--- a/packages/xforms-engine/src/lib/client-reactivity/submission/createNodeRangeSubmissionState.ts
+++ b/packages/xforms-engine/src/lib/client-reactivity/instance-state/createNodeRangeInstanceState.ts
@@ -1,9 +1,9 @@
 import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
-import type { ClientReactiveSubmittableParentNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableParentNode.ts';
+import type { ClientReactiveSerializableParentNode } from '../../../instance/internal-api/serialization/ClientReactiveSerializableParentNode.ts';
 import type { RepeatInstance } from '../../../instance/repeat/RepeatInstance.ts';
 
-export const createNodeRangeSubmissionState = (
-	node: ClientReactiveSubmittableParentNode<RepeatInstance>
+export const createNodeRangeInstanceState = (
+	node: ClientReactiveSerializableParentNode<RepeatInstance>
 ): InstanceState => {
 	return {
 		get instanceXML() {
diff --git a/packages/xforms-engine/src/lib/client-reactivity/submission/createParentNodeSubmissionState.ts b/packages/xforms-engine/src/lib/client-reactivity/instance-state/createParentNodeInstanceState.ts
similarity index 69%
rename from packages/xforms-engine/src/lib/client-reactivity/submission/createParentNodeSubmissionState.ts
rename to packages/xforms-engine/src/lib/client-reactivity/instance-state/createParentNodeInstanceState.ts
index 40530c70..c092e8d8 100644
--- a/packages/xforms-engine/src/lib/client-reactivity/submission/createParentNodeSubmissionState.ts
+++ b/packages/xforms-engine/src/lib/client-reactivity/instance-state/createParentNodeInstanceState.ts
@@ -1,10 +1,10 @@
 import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
 import type { GeneralChildNode } from '../../../instance/hierarchy.ts';
-import type { ClientReactiveSubmittableParentNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableParentNode.ts';
+import type { ClientReactiveSerializableParentNode } from '../../../instance/internal-api/serialization/ClientReactiveSerializableParentNode.ts';
 import { serializeParentElementXML } from '../../xml-serialization.ts';
 
-export const createParentNodeSubmissionState = (
-	node: ClientReactiveSubmittableParentNode<GeneralChildNode>
+export const createParentNodeInstanceState = (
+	node: ClientReactiveSerializableParentNode<GeneralChildNode>
 ): InstanceState => {
 	return {
 		get instanceXML() {
diff --git a/packages/xforms-engine/src/lib/client-reactivity/instance-state/createPrimaryInstanceState.ts b/packages/xforms-engine/src/lib/client-reactivity/instance-state/createPrimaryInstanceState.ts
new file mode 100644
index 00000000..76dbbf82
--- /dev/null
+++ b/packages/xforms-engine/src/lib/client-reactivity/instance-state/createPrimaryInstanceState.ts
@@ -0,0 +1,12 @@
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import type { ClientReactiveSerializableInstance } from '../../../instance/internal-api/serialization/ClientReactiveSerializableInstance.ts';
+
+export const createPrimaryInstanceState = (
+	node: ClientReactiveSerializableInstance
+): InstanceState => {
+	return {
+		get instanceXML(): string {
+			return node.root.instanceState.instanceXML;
+		},
+	};
+};
diff --git a/packages/xforms-engine/src/lib/client-reactivity/submission/createRootSubmissionState.ts b/packages/xforms-engine/src/lib/client-reactivity/instance-state/createRootInstanceState.ts
similarity index 89%
rename from packages/xforms-engine/src/lib/client-reactivity/submission/createRootSubmissionState.ts
rename to packages/xforms-engine/src/lib/client-reactivity/instance-state/createRootInstanceState.ts
index 06f04e48..92a0b8e9 100644
--- a/packages/xforms-engine/src/lib/client-reactivity/submission/createRootSubmissionState.ts
+++ b/packages/xforms-engine/src/lib/client-reactivity/instance-state/createRootInstanceState.ts
@@ -2,7 +2,7 @@ import type { InstanceState } from '../../../client/serialization/InstanceState.
 import type { Root } from '../../../instance/Root.ts';
 import { serializeParentElementXML } from '../../xml-serialization.ts';
 
-export const createRootSubmissionState = (node: Root): InstanceState => {
+export const createRootInstanceState = (node: Root): InstanceState => {
 	return {
 		get instanceXML() {
 			const { namespaceDeclarations, attributes } = node.definition;
diff --git a/packages/xforms-engine/src/lib/client-reactivity/submission/createValueNodeSubmissionState.ts b/packages/xforms-engine/src/lib/client-reactivity/instance-state/createValueNodeInstanceState.ts
similarity index 66%
rename from packages/xforms-engine/src/lib/client-reactivity/submission/createValueNodeSubmissionState.ts
rename to packages/xforms-engine/src/lib/client-reactivity/instance-state/createValueNodeInstanceState.ts
index 5c81358a..bdf5ee02 100644
--- a/packages/xforms-engine/src/lib/client-reactivity/submission/createValueNodeSubmissionState.ts
+++ b/packages/xforms-engine/src/lib/client-reactivity/instance-state/createValueNodeInstanceState.ts
@@ -1,9 +1,9 @@
 import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
-import type { ClientReactiveSubmittableValueNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import type { ClientReactiveSerializableValueNode } from '../../../instance/internal-api/serialization/ClientReactiveSerializableValueNode.ts';
 import { escapeXMLText, serializeLeafElementXML } from '../../xml-serialization.ts';
 
-export const createValueNodeSubmissionState = (
-	node: ClientReactiveSubmittableValueNode
+export const createValueNodeInstanceState = (
+	node: ClientReactiveSerializableValueNode
 ): InstanceState => {
 	const { qualifiedName } = node.definition;
 
diff --git a/packages/xforms-engine/src/lib/client-reactivity/submission/prepareSubmission.ts b/packages/xforms-engine/src/lib/client-reactivity/instance-state/prepareInstancePayload.ts
similarity index 72%
rename from packages/xforms-engine/src/lib/client-reactivity/submission/prepareSubmission.ts
rename to packages/xforms-engine/src/lib/client-reactivity/instance-state/prepareInstancePayload.ts
index 76f17496..1f682b0d 100644
--- a/packages/xforms-engine/src/lib/client-reactivity/submission/prepareSubmission.ts
+++ b/packages/xforms-engine/src/lib/client-reactivity/instance-state/prepareInstancePayload.ts
@@ -1,6 +1,6 @@
 import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
 import { INSTANCE_FILE_NAME, INSTANCE_FILE_TYPE } from '../../../client/constants.ts';
-import type { InstanceData } from '../../../client/serialization/InstanceData.ts';
+import type { InstanceData as ClientInstanceData } from '../../../client/serialization/InstanceData.ts';
 import type { InstanceFile as ClientInstanceFile } from '../../../client/serialization/InstanceFile.ts';
 import type {
 	ChunkedInstancePayload,
@@ -10,13 +10,13 @@ import type {
 import type { InstancePayloadType } from '../../../client/serialization/InstancePayloadOptions.ts';
 import type { SubmissionDefinition } from '../../../client/submission/SubmissionDefinition.ts';
 import type { DescendantNodeViolationReference } from '../../../client/validation.ts';
-import type { ClientReactiveSubmittableInstance } from '../../../instance/internal-api/submission/ClientReactiveSubmittableInstance.ts';
+import type { ClientReactiveSerializableInstance } from '../../../instance/internal-api/serialization/ClientReactiveSerializableInstance.ts';
 
 class InstanceFile extends File implements ClientInstanceFile {
 	override readonly name = INSTANCE_FILE_NAME;
 	override readonly type = INSTANCE_FILE_TYPE;
 
-	constructor(instanceRoot: ClientReactiveSubmittableInstance) {
+	constructor(instanceRoot: ClientReactiveSerializableInstance) {
 		const { instanceXML } = instanceRoot.instanceState;
 
 		super([instanceXML], INSTANCE_FILE_NAME, {
@@ -25,9 +25,9 @@ class InstanceFile extends File implements ClientInstanceFile {
 	}
 }
 
-type AssertSubmissionData = (data: FormData) => asserts data is InstanceData;
+type AssertInstanceData = (data: FormData) => asserts data is ClientInstanceData;
 
-const assertSubmissionData: AssertSubmissionData = (data) => {
+const assertInstanceData: AssertInstanceData = (data) => {
 	const instanceFile = data.get(INSTANCE_FILE_NAME);
 
 	if (!(instanceFile instanceof InstanceFile)) {
@@ -35,11 +35,11 @@ const assertSubmissionData: AssertSubmissionData = (data) => {
 	}
 };
 
-class InstanceSubmissionData extends FormData {
-	static from(instanceFile: InstanceFile, attachments: readonly File[]): InstanceData {
+class InstanceData extends FormData {
+	static from(instanceFile: InstanceFile, attachments: readonly File[]): ClientInstanceData {
 		const data = new this(instanceFile, attachments);
 
-		assertSubmissionData(data);
+		assertInstanceData(data);
 
 		return data;
 	}
@@ -74,11 +74,11 @@ interface ReadyValidation {
 	readonly violations: null;
 }
 
-type SubmissionInstanceStateValidation = PendingValidation | ReadyValidation;
+type InstanceStateValidation = PendingValidation | ReadyValidation;
 
-const validateSubmission = (
-	instanceRoot: ClientReactiveSubmittableInstance
-): SubmissionInstanceStateValidation => {
+const validateInstance = (
+	instanceRoot: ClientReactiveSerializableInstance
+): InstanceStateValidation => {
 	const { violations } = instanceRoot.validationState;
 
 	if (violations.length === 0) {
@@ -95,12 +95,12 @@ const validateSubmission = (
 };
 
 const monolithicInstancePayload = (
-	validation: SubmissionInstanceStateValidation,
+	validation: InstanceStateValidation,
 	definition: SubmissionDefinition,
 	instanceFile: InstanceFile,
 	attachments: readonly File[]
 ): MonolithicInstancePayload => {
-	const data = InstanceSubmissionData.from(instanceFile, attachments);
+	const data = InstanceData.from(instanceFile, attachments);
 
 	return {
 		...validation,
@@ -114,17 +114,17 @@ interface ChunkedInstancePayloadOptions {
 }
 
 const chunkedInstancePayload = (
-	validation: SubmissionInstanceStateValidation,
+	validation: InstanceStateValidation,
 	definition: SubmissionDefinition,
 	instanceFile: InstanceFile,
 	attachments: readonly File[],
 	options: ChunkedInstancePayloadOptions
 ): ChunkedInstancePayload => {
 	if (attachments.length > 0 || options.maxSize !== Infinity) {
-		throw new Error('Submission chunking pending implementation');
+		throw new Error('InstancePayload chunking pending implementation');
 	}
 
-	const data = InstanceSubmissionData.from(instanceFile, attachments);
+	const data = InstanceData.from(instanceFile, attachments);
 
 	return {
 		...validation,
@@ -133,16 +133,16 @@ const chunkedInstancePayload = (
 	};
 };
 
-export interface PrepareSubmissionOptions<PayloadType extends InstancePayloadType> {
+export interface PrepareInstancePayloadOptions<PayloadType extends InstancePayloadType> {
 	readonly payloadType: PayloadType;
 	readonly maxSize: number;
 }
 
-export const prepareSubmission = <PayloadType extends InstancePayloadType>(
-	instanceRoot: ClientReactiveSubmittableInstance,
-	options: PrepareSubmissionOptions<PayloadType>
+export const prepareInstancePayload = <PayloadType extends InstancePayloadType>(
+	instanceRoot: ClientReactiveSerializableInstance,
+	options: PrepareInstancePayloadOptions<PayloadType>
 ): InstancePayload<PayloadType> => {
-	const validation = validateSubmission(instanceRoot);
+	const validation = validateInstance(instanceRoot);
 	const definition = instanceRoot.definition.submission;
 	const instanceFile = new InstanceFile(instanceRoot);
 	const attachments: readonly File[] = [];
diff --git a/packages/xforms-engine/src/lib/client-reactivity/submission/createInstanceSubmissionState.ts b/packages/xforms-engine/src/lib/client-reactivity/submission/createInstanceSubmissionState.ts
deleted file mode 100644
index de5a433e..00000000
--- a/packages/xforms-engine/src/lib/client-reactivity/submission/createInstanceSubmissionState.ts
+++ /dev/null
@@ -1,12 +0,0 @@
-import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
-import type { ClientReactiveSubmittableInstance } from '../../../instance/internal-api/submission/ClientReactiveSubmittableInstance.ts';
-
-export const createInstanceSubmissionState = (
-	node: ClientReactiveSubmittableInstance
-): InstanceState => {
-	return {
-		get instanceXML(): string {
-			return node.root.instanceState.instanceXML;
-		},
-	};
-};
diff --git a/packages/xforms-engine/src/lib/reactivity/createInstanceValueState.ts b/packages/xforms-engine/src/lib/reactivity/createInstanceValueState.ts
index 90d21a6f..4f1d4f73 100644
--- a/packages/xforms-engine/src/lib/reactivity/createInstanceValueState.ts
+++ b/packages/xforms-engine/src/lib/reactivity/createInstanceValueState.ts
@@ -182,7 +182,7 @@ export type InstanceValueState = SimpleAtomicState<string>;
  * Provides a consistent interface for value nodes of any type which:
  *
  * - derives initial state from either an existing instance (e.g. for edits) or
- *   the node's definition (e.g. initializing a new submission)
+ *   the node's definition (e.g. initializing a new instance)
  * - decodes current primary instance state into the value node's runtime type
  * - encodes updated runtime values to store updated instance state
  * - initializes reactive computation of `calculate` bind expressions for those
diff --git a/packages/xforms-engine/src/lib/reactivity/createValueState.ts b/packages/xforms-engine/src/lib/reactivity/createValueState.ts
index 2a06947c..13497d4e 100644
--- a/packages/xforms-engine/src/lib/reactivity/createValueState.ts
+++ b/packages/xforms-engine/src/lib/reactivity/createValueState.ts
@@ -87,7 +87,7 @@ type RuntimeValueState<RuntimeValue> = SimpleAtomicState<RuntimeValue>;
  *
  * - Values written by a node will be {@link ValueContext.encodeValue | encoded}
  *   (also as implemented by that node) into a string value appropriate for
- *   serialization in an instance submission.
+ *   serialization an instance.
  */
 const createRuntimeValueState = <RuntimeValue>(
 	context: ValueContext<RuntimeValue>,
@@ -171,7 +171,7 @@ type ValueState<RuntimeValue> = SimpleAtomicState<RuntimeValue>;
  * Provides a consistent interface for value nodes of any type which:
  *
  * - derives initial state from either an existing instance (e.g. for edits) or
- *   the node's definition (e.g. initializing a new submission)
+ *   the node's definition (e.g. initializing a new instance)
  * - decodes current primary instance state into the value node's runtime type
  * - encodes updated runtime values to store updated instance state
  * - initializes reactive computation of `calculate` bind expressions for those

From dfccc7833dede5b8e9bfa1490aa745e914bffbdb Mon Sep 17 00:00:00 2001
From: eyelidlessness <gnosis@gmail.com>
Date: Wed, 26 Feb 2025 14:36:09 -0800
Subject: [PATCH 5/8] engine: Improve clarity of submission metadata on
 `InstancePayload`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

As noted in the changeset included in this commit: this is a **BREAKING CHANGE**.

It will impact:

- Clients: accessing the property directly
- Host applications: accessing the property where an `InstancePayload` is passed directly through engine -> client -> host app

I’ve confirmed with the Central team that this change will not be disruptive for integration!
---
 .changeset/new-dolls-dress.md                    |  5 +++++
 .../src/assertion/extensions/submission.ts       |  2 +-
 packages/scenario/test/submission.test.ts        | 16 ++++++++--------
 .../src/client/serialization/InstancePayload.ts  |  5 +++--
 ...SubmissionDefinition.ts => SubmissionMeta.ts} |  2 +-
 packages/xforms-engine/src/index.ts              |  2 +-
 .../ClientReactiveSerializableInstance.ts        |  4 ++--
 .../instance-state/prepareInstancePayload.ts     | 16 ++++++++--------
 .../src/parse/model/ModelDefinition.ts           |  5 +++--
 .../src/parse/model/RootDefinition.ts            |  4 ++--
 ...sionDefinition.ts => SubmissionDefinition.ts} |  4 ++--
 11 files changed, 36 insertions(+), 29 deletions(-)
 create mode 100644 .changeset/new-dolls-dress.md
 rename packages/xforms-engine/src/client/submission/{SubmissionDefinition.ts => SubmissionMeta.ts} (92%)
 rename packages/xforms-engine/src/parse/model/{FormSubmissionDefinition.ts => SubmissionDefinition.ts} (88%)

diff --git a/.changeset/new-dolls-dress.md b/.changeset/new-dolls-dress.md
new file mode 100644
index 00000000..fc719ef2
--- /dev/null
+++ b/.changeset/new-dolls-dress.md
@@ -0,0 +1,5 @@
+---
+'@getodk/xforms-engine': minor
+---
+
+**BREAKING CHANGE** rename instance payload property `definition` to `SubmissionMeta`
diff --git a/packages/scenario/src/assertion/extensions/submission.ts b/packages/scenario/src/assertion/extensions/submission.ts
index 62a854e6..0a7509c1 100644
--- a/packages/scenario/src/assertion/extensions/submission.ts
+++ b/packages/scenario/src/assertion/extensions/submission.ts
@@ -56,7 +56,7 @@ const assertInstancePayload: AssertIs<AnyInstancePayload> = (value) => {
 	if (value.violations !== null) {
 		assertUnknownArray(value.violations);
 	}
-	assertUnknownObject(value.definition);
+	assertUnknownObject(value.submissionMeta);
 
 	if (Array.isArray(value.data)) {
 		value.data.forEach((item) => {
diff --git a/packages/scenario/test/submission.test.ts b/packages/scenario/test/submission.test.ts
index 0667b396..62edc015 100644
--- a/packages/scenario/test/submission.test.ts
+++ b/packages/scenario/test/submission.test.ts
@@ -750,26 +750,26 @@ describe('Form submission', () => {
 			return scenario;
 		};
 
-		describe('submission definition', () => {
-			it('includes a default submission definition', async () => {
+		describe('submission meta', () => {
+			it('includes default submission meta', async () => {
 				const scenario = await buildSubmissionPayloadScenario();
 				const submissionResult = await scenario.prepareWebFormsSubmission();
 
-				expect(submissionResult.definition).toMatchObject({
+				expect(submissionResult.submissionMeta).toMatchObject({
 					submissionAction: null,
 					submissionMethod: 'post',
 					encryptionKey: null,
 				});
 			});
 
-			it('includes a form-specified submission definition URL', async () => {
+			it('includes a form-specified submission URL', async () => {
 				const submissionAction = 'https://example.org';
 				const scenario = await buildSubmissionPayloadScenario({
 					submissionElements: [t(`submission action="${submissionAction}"`)],
 				});
 				const submissionResult = await scenario.prepareWebFormsSubmission();
 
-				expect(submissionResult.definition).toMatchObject({
+				expect(submissionResult.submissionMeta).toMatchObject({
 					submissionAction: new URL(submissionAction),
 				});
 			});
@@ -780,7 +780,7 @@ describe('Form submission', () => {
 				});
 				const submissionResult = await scenario.prepareWebFormsSubmission();
 
-				expect(submissionResult.definition).toMatchObject({
+				expect(submissionResult.submissionMeta).toMatchObject({
 					submissionMethod: 'post',
 				});
 			});
@@ -791,7 +791,7 @@ describe('Form submission', () => {
 				});
 				const submissionResult = await scenario.prepareWebFormsSubmission();
 
-				expect(submissionResult.definition).toMatchObject({
+				expect(submissionResult.submissionMeta).toMatchObject({
 					submissionMethod: 'post',
 				});
 			});
@@ -825,7 +825,7 @@ describe('Form submission', () => {
 				});
 				const submissionResult = await scenario.prepareWebFormsSubmission();
 
-				expect(submissionResult.definition).toMatchObject({
+				expect(submissionResult.submissionMeta).toMatchObject({
 					encryptionKey: base64RsaPublicKey,
 				});
 			});
diff --git a/packages/xforms-engine/src/client/serialization/InstancePayload.ts b/packages/xforms-engine/src/client/serialization/InstancePayload.ts
index 9d401d36..986a2a16 100644
--- a/packages/xforms-engine/src/client/serialization/InstancePayload.ts
+++ b/packages/xforms-engine/src/client/serialization/InstancePayload.ts
@@ -1,4 +1,4 @@
-import type { SubmissionDefinition } from '../submission/SubmissionDefinition.ts';
+import type { SubmissionMeta } from '../submission/SubmissionMeta.ts';
 import type { AnyViolation, DescendantNodeViolationReference } from '../validation.ts';
 import type { InstanceData } from './InstanceData.ts';
 import type { InstancePayloadOptions, InstancePayloadType } from './InstancePayloadOptions.ts';
@@ -80,7 +80,8 @@ type InstancePayloadViolation =
 
 interface BaseInstancePayload<PayloadType extends InstancePayloadType> {
 	readonly status: InstancePayloadStatus;
-	readonly definition: SubmissionDefinition;
+	readonly submissionMeta: SubmissionMeta;
+
 	get violations(): readonly InstancePayloadViolation[] | null;
 
 	/**
diff --git a/packages/xforms-engine/src/client/submission/SubmissionDefinition.ts b/packages/xforms-engine/src/client/submission/SubmissionMeta.ts
similarity index 92%
rename from packages/xforms-engine/src/client/submission/SubmissionDefinition.ts
rename to packages/xforms-engine/src/client/submission/SubmissionMeta.ts
index d458f77f..48eb4453 100644
--- a/packages/xforms-engine/src/client/submission/SubmissionDefinition.ts
+++ b/packages/xforms-engine/src/client/submission/SubmissionMeta.ts
@@ -1,4 +1,4 @@
-export interface SubmissionDefinition {
+export interface SubmissionMeta {
 	/**
 	 * @see {@link https://getodk.github.io/xforms-spec/#submission-attributes | `action` submission attribute}
 	 */
diff --git a/packages/xforms-engine/src/index.ts b/packages/xforms-engine/src/index.ts
index 1f7e5e2f..91ea04c6 100644
--- a/packages/xforms-engine/src/index.ts
+++ b/packages/xforms-engine/src/index.ts
@@ -37,7 +37,7 @@ export type * from './client/serialization/InstanceFile.ts';
 export type * from './client/serialization/InstancePayload.ts';
 export type * from './client/serialization/InstancePayloadOptions.ts';
 export type * from './client/serialization/InstanceState.ts';
-export type * from './client/submission/SubmissionDefinition.ts';
+export type * from './client/submission/SubmissionMeta.ts';
 export type * from './client/SubtreeNode.ts';
 export type * from './client/TextRange.ts';
 export type * from './client/TriggerNode.ts';
diff --git a/packages/xforms-engine/src/instance/internal-api/serialization/ClientReactiveSerializableInstance.ts b/packages/xforms-engine/src/instance/internal-api/serialization/ClientReactiveSerializableInstance.ts
index 1fde0a8e..3eef79a2 100644
--- a/packages/xforms-engine/src/instance/internal-api/serialization/ClientReactiveSerializableInstance.ts
+++ b/packages/xforms-engine/src/instance/internal-api/serialization/ClientReactiveSerializableInstance.ts
@@ -1,4 +1,4 @@
-import type { SubmissionDefinition } from '../../../client/submission/SubmissionDefinition.ts';
+import type { SubmissionMeta } from '../../../client/submission/SubmissionMeta.ts';
 import type { AncestorNodeValidationState } from '../../../client/validation.ts';
 import type { Root } from '../../Root.ts';
 import type {
@@ -8,7 +8,7 @@ import type {
 
 interface ClientReactiveSerializableInstanceDefinition
 	extends ClientReactiveSerializableParentNodeDefinition {
-	readonly submission: SubmissionDefinition;
+	readonly submission: SubmissionMeta;
 }
 
 export interface ClientReactiveSerializableInstance
diff --git a/packages/xforms-engine/src/lib/client-reactivity/instance-state/prepareInstancePayload.ts b/packages/xforms-engine/src/lib/client-reactivity/instance-state/prepareInstancePayload.ts
index 1f682b0d..8f796921 100644
--- a/packages/xforms-engine/src/lib/client-reactivity/instance-state/prepareInstancePayload.ts
+++ b/packages/xforms-engine/src/lib/client-reactivity/instance-state/prepareInstancePayload.ts
@@ -8,7 +8,7 @@ import type {
 	MonolithicInstancePayload,
 } from '../../../client/serialization/InstancePayload.ts';
 import type { InstancePayloadType } from '../../../client/serialization/InstancePayloadOptions.ts';
-import type { SubmissionDefinition } from '../../../client/submission/SubmissionDefinition.ts';
+import type { SubmissionMeta } from '../../../client/submission/SubmissionMeta.ts';
 import type { DescendantNodeViolationReference } from '../../../client/validation.ts';
 import type { ClientReactiveSerializableInstance } from '../../../instance/internal-api/serialization/ClientReactiveSerializableInstance.ts';
 
@@ -96,7 +96,7 @@ const validateInstance = (
 
 const monolithicInstancePayload = (
 	validation: InstanceStateValidation,
-	definition: SubmissionDefinition,
+	submissionMeta: SubmissionMeta,
 	instanceFile: InstanceFile,
 	attachments: readonly File[]
 ): MonolithicInstancePayload => {
@@ -104,7 +104,7 @@ const monolithicInstancePayload = (
 
 	return {
 		...validation,
-		definition,
+		submissionMeta,
 		data,
 	};
 };
@@ -115,7 +115,7 @@ interface ChunkedInstancePayloadOptions {
 
 const chunkedInstancePayload = (
 	validation: InstanceStateValidation,
-	definition: SubmissionDefinition,
+	submissionMeta: SubmissionMeta,
 	instanceFile: InstanceFile,
 	attachments: readonly File[],
 	options: ChunkedInstancePayloadOptions
@@ -128,7 +128,7 @@ const chunkedInstancePayload = (
 
 	return {
 		...validation,
-		definition,
+		submissionMeta,
 		data: [data],
 	};
 };
@@ -143,7 +143,7 @@ export const prepareInstancePayload = <PayloadType extends InstancePayloadType>(
 	options: PrepareInstancePayloadOptions<PayloadType>
 ): InstancePayload<PayloadType> => {
 	const validation = validateInstance(instanceRoot);
-	const definition = instanceRoot.definition.submission;
+	const submissionMeta = instanceRoot.definition.submission;
 	const instanceFile = new InstanceFile(instanceRoot);
 	const attachments: readonly File[] = [];
 
@@ -151,7 +151,7 @@ export const prepareInstancePayload = <PayloadType extends InstancePayloadType>(
 		case 'chunked':
 			return chunkedInstancePayload(
 				validation,
-				definition,
+				submissionMeta,
 				instanceFile,
 				attachments,
 				options
@@ -160,7 +160,7 @@ export const prepareInstancePayload = <PayloadType extends InstancePayloadType>(
 		case 'monolithic':
 			return monolithicInstancePayload(
 				validation,
-				definition,
+				submissionMeta,
 				instanceFile,
 				attachments
 			) satisfies MonolithicInstancePayload as InstancePayload<PayloadType>;
diff --git a/packages/xforms-engine/src/parse/model/ModelDefinition.ts b/packages/xforms-engine/src/parse/model/ModelDefinition.ts
index 73cab44d..0cc1dbba 100644
--- a/packages/xforms-engine/src/parse/model/ModelDefinition.ts
+++ b/packages/xforms-engine/src/parse/model/ModelDefinition.ts
@@ -1,8 +1,8 @@
 import type { XFormDefinition } from '../XFormDefinition.ts';
-import { FormSubmissionDefinition } from './FormSubmissionDefinition.ts';
 import { ItextTranslationsDefinition } from './ItextTranslation/ItextTranslationsDefinition.ts';
 import { ModelBindMap } from './ModelBindMap.ts';
 import { RootDefinition } from './RootDefinition.ts';
+import { SubmissionDefinition } from './SubmissionDefinition.ts';
 
 export class ModelDefinition {
 	readonly binds: ModelBindMap;
@@ -10,7 +10,8 @@ export class ModelDefinition {
 	readonly itextTranslations: ItextTranslationsDefinition;
 
 	constructor(readonly form: XFormDefinition) {
-		const submission = new FormSubmissionDefinition(form.xformDOM);
+		const submission = new SubmissionDefinition(form.xformDOM);
+
 		this.binds = ModelBindMap.fromModel(this);
 		this.root = new RootDefinition(form, this, submission, form.body.classes);
 		this.itextTranslations = ItextTranslationsDefinition.from(form.xformDOM);
diff --git a/packages/xforms-engine/src/parse/model/RootDefinition.ts b/packages/xforms-engine/src/parse/model/RootDefinition.ts
index a1cdb72a..4545d634 100644
--- a/packages/xforms-engine/src/parse/model/RootDefinition.ts
+++ b/packages/xforms-engine/src/parse/model/RootDefinition.ts
@@ -2,7 +2,6 @@ import { NamespaceDeclarationMap } from '../../lib/names/NamespaceDeclarationMap
 import { QualifiedName } from '../../lib/names/QualifiedName.ts';
 import type { BodyClassList } from '../body/BodyDefinition.ts';
 import type { XFormDefinition } from '../XFormDefinition.ts';
-import type { FormSubmissionDefinition } from './FormSubmissionDefinition.ts';
 import { LeafNodeDefinition } from './LeafNodeDefinition.ts';
 import type { ModelDefinition } from './ModelDefinition.ts';
 import type { ChildNodeDefinition, ParentNodeDefinition } from './NodeDefinition.ts';
@@ -11,6 +10,7 @@ import { NoteNodeDefinition } from './NoteNodeDefinition.ts';
 import { RangeNodeDefinition } from './RangeNodeDefinition.ts';
 import { RepeatRangeDefinition } from './RepeatRangeDefinition.ts';
 import { RootAttributeMap } from './RootAttributeMap.ts';
+import type { SubmissionDefinition } from './SubmissionDefinition.ts';
 import { SubtreeDefinition } from './SubtreeDefinition.ts';
 
 export class RootDefinition extends NodeDefinition<'root'> {
@@ -31,7 +31,7 @@ export class RootDefinition extends NodeDefinition<'root'> {
 	constructor(
 		protected readonly form: XFormDefinition,
 		protected readonly model: ModelDefinition,
-		readonly submission: FormSubmissionDefinition,
+		readonly submission: SubmissionDefinition,
 		readonly classes: BodyClassList
 	) {
 		const { primaryInstanceRoot } = form.xformDOM;
diff --git a/packages/xforms-engine/src/parse/model/FormSubmissionDefinition.ts b/packages/xforms-engine/src/parse/model/SubmissionDefinition.ts
similarity index 88%
rename from packages/xforms-engine/src/parse/model/FormSubmissionDefinition.ts
rename to packages/xforms-engine/src/parse/model/SubmissionDefinition.ts
index 929e76ff..54b0beec 100644
--- a/packages/xforms-engine/src/parse/model/FormSubmissionDefinition.ts
+++ b/packages/xforms-engine/src/parse/model/SubmissionDefinition.ts
@@ -1,8 +1,8 @@
-import type { SubmissionDefinition } from '../../client/submission/SubmissionDefinition.ts';
+import type { SubmissionMeta } from '../../client/submission/SubmissionMeta.ts';
 import { getSubmissionElement } from '../../lib/dom/query.ts';
 import type { XFormDOM } from '../XFormDOM.ts';
 
-export class FormSubmissionDefinition implements SubmissionDefinition {
+export class SubmissionDefinition implements SubmissionMeta {
 	readonly submissionAction!: URL | null;
 	readonly submissionMethod = 'post';
 	readonly encryptionKey!: string | null;

From 0005cc68d9c80da61b8a0b8c0bd3eb2fa697bde7 Mon Sep 17 00:00:00 2001
From: eyelidlessness <gnosis@gmail.com>
Date: Thu, 27 Feb 2025 13:22:51 -0800
Subject: [PATCH 6/8] engine: more consistent shape of `InstancePayload.data`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

As noted in the changeset included in this commit: this is a **BREAKING CHANGE**.

With this change, `InstancePayload<'monolithic'>.data` is represented as a single-item tuple. This makes it a subset of `InstancePayload<'chunked'>.data` (which is a tuple of one or more items).

It will impact:

- Clients: accessing `InstancePayload<'monolithic'>.data` directly
- Host applications: accessing the same data passed through engine -> client -> host app

I’ve confirmed with the Central team that this change will not be disruptive for integration!
---
 .changeset/pretty-grapes-applaud.md           |  5 ++++
 .../src/assertion/extensions/submission.ts    | 29 ++-----------------
 .../client/serialization/InstancePayload.ts   |  2 +-
 .../instance-state/prepareInstancePayload.ts  |  2 +-
 4 files changed, 9 insertions(+), 29 deletions(-)
 create mode 100644 .changeset/pretty-grapes-applaud.md

diff --git a/.changeset/pretty-grapes-applaud.md b/.changeset/pretty-grapes-applaud.md
new file mode 100644
index 00000000..7d32721c
--- /dev/null
+++ b/.changeset/pretty-grapes-applaud.md
@@ -0,0 +1,5 @@
+---
+'@getodk/xforms-engine': minor
+---
+
+**BREAKING CHANGE** instance payload data is always produced as a tuple. The shape for a "chunked" payload is unchanged. The shape for a "monolithic" payload is now more like a "chunked" payload, except that it is guaranteed to always have only one item.
diff --git a/packages/scenario/src/assertion/extensions/submission.ts b/packages/scenario/src/assertion/extensions/submission.ts
index 0a7509c1..03aff8cf 100644
--- a/packages/scenario/src/assertion/extensions/submission.ts
+++ b/packages/scenario/src/assertion/extensions/submission.ts
@@ -11,12 +11,7 @@ import {
 } from '@getodk/common/test/assertions/helpers.ts';
 import type { SimpleAssertionResult } from '@getodk/common/test/assertions/vitest/shared-extension-types.ts';
 import type { AssertIs } from '@getodk/common/types/assertions/AssertIs.ts';
-import type {
-	InstanceData,
-	InstanceFile,
-	InstancePayload,
-	InstancePayloadType,
-} from '@getodk/xforms-engine';
+import type { InstanceFile, InstancePayload, InstancePayloadType } from '@getodk/xforms-engine';
 import { constants } from '@getodk/xforms-engine';
 import { assert, expect } from 'vitest';
 import { Scenario } from '../../jr/Scenario.ts';
@@ -83,28 +78,8 @@ const assertInstanceFile: AssertIs<InstanceFile> = (value) => {
 	}
 };
 
-type ChunkedInstanceData = readonly [InstanceData, ...InstanceData[]];
-
-const isChunkedSubmissionData = (
-	data: ChunkedInstanceData | InstanceData
-): data is ChunkedInstanceData => {
-	return Array.isArray(data);
-};
-
-const getInstanceData = (payload: AnyInstancePayload): InstanceData => {
-	const { data } = payload;
-
-	if (isChunkedSubmissionData(data)) {
-		const [first] = data;
-
-		return first;
-	}
-
-	return data;
-};
-
 const getInstanceFile = (payload: AnyInstancePayload): InstanceFile => {
-	const instanceData = getInstanceData(payload);
+	const [instanceData] = payload.data;
 	const file = instanceData.get(INSTANCE_FILE_NAME);
 
 	assertInstanceFile(file);
diff --git a/packages/xforms-engine/src/client/serialization/InstancePayload.ts b/packages/xforms-engine/src/client/serialization/InstancePayload.ts
index 986a2a16..f765f734 100644
--- a/packages/xforms-engine/src/client/serialization/InstancePayload.ts
+++ b/packages/xforms-engine/src/client/serialization/InstancePayload.ts
@@ -13,7 +13,7 @@ export type InstancePayloadStatus =
 // prettier-ignore
 type InstancePayloadData<PayloadType extends InstancePayloadType> = {
 	chunked: readonly [InstanceData, ...InstanceData[]];
-	monolithic: InstanceData;
+	monolithic: readonly [InstanceData];
 }[PayloadType];
 
 /**
diff --git a/packages/xforms-engine/src/lib/client-reactivity/instance-state/prepareInstancePayload.ts b/packages/xforms-engine/src/lib/client-reactivity/instance-state/prepareInstancePayload.ts
index 8f796921..a46a139f 100644
--- a/packages/xforms-engine/src/lib/client-reactivity/instance-state/prepareInstancePayload.ts
+++ b/packages/xforms-engine/src/lib/client-reactivity/instance-state/prepareInstancePayload.ts
@@ -105,7 +105,7 @@ const monolithicInstancePayload = (
 	return {
 		...validation,
 		submissionMeta,
-		data,
+		data: [data],
 	};
 };
 

From 79291b9cb76e177bdd99fcb68f34821033936644 Mon Sep 17 00:00:00 2001
From: eyelidlessness <gnosis@gmail.com>
Date: Thu, 27 Feb 2025 08:18:43 -0800
Subject: [PATCH 7/8] =?UTF-8?q?scenario:=20reflect=20=E2=80=9Csubmission?=
 =?UTF-8?q?=E2=80=9D=20->=20=E2=80=9Cinstance=E2=80=9D=20terminology?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/scenario/src/jr/Scenario.ts      |  2 +-
 packages/scenario/test/submission.test.ts | 18 +++++++++---------
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/packages/scenario/src/jr/Scenario.ts b/packages/scenario/src/jr/Scenario.ts
index 003e3d21..bbaef6cd 100644
--- a/packages/scenario/src/jr/Scenario.ts
+++ b/packages/scenario/src/jr/Scenario.ts
@@ -974,7 +974,7 @@ export class Scenario {
 	 * more about Collect's responsibility for submission (beyond serialization,
 	 * already handled by {@link proposed_serializeInstance}).
 	 */
-	prepareWebFormsSubmission() {
+	prepareWebFormsInstancePayload() {
 		return this.instanceRoot.prepareInstancePayload();
 	}
 
diff --git a/packages/scenario/test/submission.test.ts b/packages/scenario/test/submission.test.ts
index 62edc015..df32aa7c 100644
--- a/packages/scenario/test/submission.test.ts
+++ b/packages/scenario/test/submission.test.ts
@@ -753,7 +753,7 @@ describe('Form submission', () => {
 		describe('submission meta', () => {
 			it('includes default submission meta', async () => {
 				const scenario = await buildSubmissionPayloadScenario();
-				const submissionResult = await scenario.prepareWebFormsSubmission();
+				const submissionResult = await scenario.prepareWebFormsInstancePayload();
 
 				expect(submissionResult.submissionMeta).toMatchObject({
 					submissionAction: null,
@@ -767,7 +767,7 @@ describe('Form submission', () => {
 				const scenario = await buildSubmissionPayloadScenario({
 					submissionElements: [t(`submission action="${submissionAction}"`)],
 				});
-				const submissionResult = await scenario.prepareWebFormsSubmission();
+				const submissionResult = await scenario.prepareWebFormsInstancePayload();
 
 				expect(submissionResult.submissionMeta).toMatchObject({
 					submissionAction: new URL(submissionAction),
@@ -778,7 +778,7 @@ describe('Form submission', () => {
 				const scenario = await buildSubmissionPayloadScenario({
 					submissionElements: [t('submission method="post"')],
 				});
-				const submissionResult = await scenario.prepareWebFormsSubmission();
+				const submissionResult = await scenario.prepareWebFormsInstancePayload();
 
 				expect(submissionResult.submissionMeta).toMatchObject({
 					submissionMethod: 'post',
@@ -789,7 +789,7 @@ describe('Form submission', () => {
 				const scenario = await buildSubmissionPayloadScenario({
 					submissionElements: [t('submission method="form-data-post"')],
 				});
-				const submissionResult = await scenario.prepareWebFormsSubmission();
+				const submissionResult = await scenario.prepareWebFormsInstancePayload();
 
 				expect(submissionResult.submissionMeta).toMatchObject({
 					submissionMethod: 'post',
@@ -823,7 +823,7 @@ describe('Form submission', () => {
 						),
 					],
 				});
-				const submissionResult = await scenario.prepareWebFormsSubmission();
+				const submissionResult = await scenario.prepareWebFormsInstancePayload();
 
 				expect(submissionResult.submissionMeta).toMatchObject({
 					encryptionKey: base64RsaPublicKey,
@@ -858,13 +858,13 @@ describe('Form submission', () => {
 				});
 
 				it('is ready for submission when instance state is valid', async () => {
-					const submissionResult = await scenario.prepareWebFormsSubmission();
+					const submissionResult = await scenario.prepareWebFormsInstancePayload();
 
 					expect(submissionResult).toBeReadyForSubmission();
 				});
 
 				it('includes submission instance XML file data', async () => {
-					const submissionResult = await scenario.prepareWebFormsSubmission();
+					const submissionResult = await scenario.prepareWebFormsInstancePayload();
 
 					await expect(submissionResult).toHavePreparedSubmissionXML(validSubmissionXML);
 				});
@@ -895,13 +895,13 @@ describe('Form submission', () => {
 				});
 
 				it('is pending submission with violations', async () => {
-					const submissionResult = await scenario.prepareWebFormsSubmission();
+					const submissionResult = await scenario.prepareWebFormsInstancePayload();
 
 					expect(submissionResult).toBePendingSubmissionWithViolations();
 				});
 
 				it('produces submission instance XML file data even when current instance state is invalid', async () => {
-					const submissionResult = await scenario.prepareWebFormsSubmission();
+					const submissionResult = await scenario.prepareWebFormsInstancePayload();
 
 					await expect(submissionResult).toHavePreparedSubmissionXML(invalidSubmissionXML);
 				});

From 553aa255b8459c418573e61143ddf442f1913ff2 Mon Sep 17 00:00:00 2001
From: eyelidlessness <gnosis@gmail.com>
Date: Thu, 27 Feb 2025 13:28:19 -0800
Subject: [PATCH 8/8] engine: make `InstancePayload` payload type explicit

This will be useful for deserialization use cases, e.g. for editing an instance-in-progress, where the payload may have been through a round trip to/from a persistence layer.
---
 .../xforms-engine/src/client/serialization/InstancePayload.ts   | 1 +
 .../client-reactivity/instance-state/prepareInstancePayload.ts  | 2 ++
 2 files changed, 3 insertions(+)

diff --git a/packages/xforms-engine/src/client/serialization/InstancePayload.ts b/packages/xforms-engine/src/client/serialization/InstancePayload.ts
index f765f734..d198ae2f 100644
--- a/packages/xforms-engine/src/client/serialization/InstancePayload.ts
+++ b/packages/xforms-engine/src/client/serialization/InstancePayload.ts
@@ -79,6 +79,7 @@ type InstancePayloadViolation =
 	| MaxSizeViolation;
 
 interface BaseInstancePayload<PayloadType extends InstancePayloadType> {
+	readonly payloadType: PayloadType;
 	readonly status: InstancePayloadStatus;
 	readonly submissionMeta: SubmissionMeta;
 
diff --git a/packages/xforms-engine/src/lib/client-reactivity/instance-state/prepareInstancePayload.ts b/packages/xforms-engine/src/lib/client-reactivity/instance-state/prepareInstancePayload.ts
index a46a139f..dbace341 100644
--- a/packages/xforms-engine/src/lib/client-reactivity/instance-state/prepareInstancePayload.ts
+++ b/packages/xforms-engine/src/lib/client-reactivity/instance-state/prepareInstancePayload.ts
@@ -103,6 +103,7 @@ const monolithicInstancePayload = (
 	const data = InstanceData.from(instanceFile, attachments);
 
 	return {
+		payloadType: 'monolithic',
 		...validation,
 		submissionMeta,
 		data: [data],
@@ -127,6 +128,7 @@ const chunkedInstancePayload = (
 	const data = InstanceData.from(instanceFile, attachments);
 
 	return {
+		payloadType: 'chunked',
 		...validation,
 		submissionMeta,
 		data: [data],