@getodk/xforms-engine 0.3.0 → 0.5.0

package/src/client/constants.ts

@@ -1,5 +1,66 @@
+import type { PrimaryInstance } from '../instance/PrimaryInstance.ts';
+import type { InitializeForm } from './index.ts';
 import type { ValidationTextRole } from './TextRange.ts';
 
+export const MISSING_RESOURCE_BEHAVIOR = {
+	/**
+	 * When this behavior is configured, {@link InitializeForm | initializing} a
+	 * {@link PrimaryInstance} for a form which references any **missing**
+	 * resources will fail, producing an error to the calling client.
+	 *
+	 * @see {@link MissingResourceBehavior}
+	 */
+	ERROR: 'ERROR',
+
+	/**
+	 * When this behavior is configured, {@link InitializeForm | initializing} a
+	 * {@link PrimaryInstance} for a form which references any **missing**
+	 * resources will succeed (producing a warning).
+	 *
+	 * Such missing resources will be parsed as if they are blank, as appropriate
+	 * for the resource's XForm semantic usage and/or format.
+	 *
+	 * @see {@link MissingResourceBehavior}
+	 */
+	BLANK: 'BLANK',
+
+	/**
+	 * @see {@link MISSING_RESOURCE_BEHAVIOR.ERROR}
+	 */
+	get DEFAULT(): 'ERROR' {
+		return MISSING_RESOURCE_BEHAVIOR.ERROR;
+	},
+} as const;
+
+export type MissingResourceBehaviorError = typeof MISSING_RESOURCE_BEHAVIOR.ERROR;
+
+export type MissingResourceBehaviorBlank = typeof MISSING_RESOURCE_BEHAVIOR.BLANK;
+
+export type MissingResourceBehaviorDefault = typeof MISSING_RESOURCE_BEHAVIOR.DEFAULT;
+
+/**
+ * Specifies behavior for {@link InitializeForm | initializing} a form's
+ * {@link PrimaryInstance} which references any **missing** resources.
+ *
+ * Here the term "missing" is consistent with
+ * {@link https://www.rfc-editor.org/rfc/rfc9110#status.404 | HTTP 404 status}
+ * semantics. Clients which provide access to form attachments by performing
+ * HTTP network requests (e.g. with {@link fetch}) can generally convey this
+ * semantic meaning with a standard {@link Response}.
+ *
+ * **IMPORTANT**
+ *
+ * The term "missing" is distinct from other network/IO failures, e.g. when
+ * network access itself is unavailable. In these cases, the engine will
+ * consider a resource's availability **ambiguous**, producing an error
+ * regardless of the configured behavior for **missing** resources.
+ */
+// prettier-ignore
+export type MissingResourceBehavior =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| MissingResourceBehaviorError
+	| MissingResourceBehaviorBlank;
+
 export const VALIDATION_TEXT = {
 	constraintMsg: 'Condition not satisfied: constraint',
 	requiredMsg: 'Condition not satisfied: required',
@@ -8,3 +69,9 @@ export const VALIDATION_TEXT = {
 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 SUBMISSION_INSTANCE_FILE_TYPE = 'text/xml';
+export type SubmissionInstanceFileType = typeof SUBMISSION_INSTANCE_FILE_TYPE;

package/src/client/hierarchy.ts

@@ -1,25 +1,37 @@
 import type { ExpandUnion } from '@getodk/common/types/helpers.d.ts';
 import type { GroupNode } from './GroupNode.ts';
-import type { ModelValueNode } from './ModelValueNode.ts';
+import type { AnyInputNode } from './InputNode.ts';
+import type { AnyModelValueNode } from './ModelValueNode.ts';
 import type { NoteNode } from './NoteNode.ts';
 import type { RepeatInstanceNode } from './repeat/RepeatInstanceNode.ts';
 import type { RepeatRangeControlledNode } from './repeat/RepeatRangeControlledNode.ts';
 import type { RepeatRangeUncontrolledNode } from './repeat/RepeatRangeUncontrolledNode.ts';
 import type { RootNode } from './RootNode.ts';
 import type { SelectNode } from './SelectNode.ts';
-import type { StringNode } from './StringNode.ts';
 import type { SubtreeNode } from './SubtreeNode.ts';
+import type { TriggerNode } from './TriggerNode.ts';
+import type { RangeNode } from './unsupported/RangeNode.ts';
+import type { RankNode } from './unsupported/RankNode.ts';
+import type { UploadNode } from './unsupported/UploadNode.ts';
+
+// prettier-ignore
+export type AnyUnsupportedControlNode =
+	| RangeNode
+	| RankNode
+	| UploadNode;
 
 // prettier-ignore
 export type AnyControlNode =
+	| AnyInputNode
 	| NoteNode
 	| SelectNode
-	| StringNode;
+	| TriggerNode;
 
 // prettier-ignore
 export type AnyLeafNode =
 	| AnyControlNode
-	| ModelValueNode;
+	| AnyModelValueNode
+	| AnyUnsupportedControlNode;
 
 // prettier-ignore
 export type RepeatRangeNode =

package/src/client/identity.ts

@@ -0,0 +1,16 @@
+type ODKXFormsUUID = `uuid:${string}`;
+
+/**
+ * @see {@link https://getodk.github.io/xforms-spec/#metadata}
+ */
+export type InstanceID = ODKXFormsUUID;
+
+/**
+ * @see {@link https://getodk.github.io/xforms-spec/#metadata}
+ */
+export type DeprecatedID = ODKXFormsUUID;
+
+/**
+ * Represents a session-stable identifier for any particular node i
+ */
+export type FormNodeID = `node:${string}`;

package/src/client/node-types.ts

@@ -1,7 +1,23 @@
+// prettier-ignore
+export type UnsupportedControlNodeType =
+	| 'range'
+	| 'rank'
+	| 'upload';
+
 // prettier-ignore
 export type RepeatRangeNodeType =
 	| 'repeat-range:controlled'
-	| 'repeat-range:uncontrolled'
+	| 'repeat-range:uncontrolled';
+
+// prettier-ignore
+export type LeafNodeType =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| 'model-value'
+	| 'note'
+	| 'select'
+	| 'input'
+	| 'trigger'
+	| UnsupportedControlNodeType;
 
 // prettier-ignore
 export type InstanceNodeType =
@@ -11,7 +27,5 @@ export type InstanceNodeType =
 	| 'repeat-instance'
 	| 'group'
 	| 'subtree'
-	| 'model-value'
-	| 'note'
-	| 'select'
-	| 'string';
+	| LeafNodeType
+	| UnsupportedControlNodeType;

package/src/client/repeat/BaseRepeatRangeNode.ts

@@ -1,4 +1,4 @@
-import type { AnyRepeatRangeDefinition } from '../../model/RepeatRangeDefinition.ts';
+import type { AnyRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
 import type { BaseNode, BaseNodeState } from '../BaseNode.ts';
 import type { NodeAppearances } from '../NodeAppearances.ts';
 import type { RootNode } from '../RootNode.ts';

package/src/client/repeat/RepeatInstanceNode.ts

@@ -1,5 +1,5 @@
-import type { RepeatInstanceDefinition } from '../../model/RepeatInstanceDefinition.ts';
-import type { RepeatTemplateDefinition } from '../../model/RepeatTemplateDefinition.ts';
+import type { RepeatInstanceDefinition } from '../../parse/model/RepeatInstanceDefinition.ts';
+import type { RepeatTemplateDefinition } from '../../parse/model/RepeatTemplateDefinition.ts';
 import type { BaseNode, BaseNodeState } from '../BaseNode.ts';
 import type { GeneralChildNode, RepeatRangeNode } from '../hierarchy.ts';
 import type { NodeAppearances } from '../NodeAppearances.ts';

package/src/client/repeat/RepeatRangeControlledNode.ts

@@ -1,4 +1,4 @@
-import type { ControlledRepeatRangeDefinition } from '../../model/RepeatRangeDefinition.ts';
+import type { ControlledRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
 import type { BaseRepeatRangeNode, BaseRepeatRangeNodeState } from './BaseRepeatRangeNode.ts';
 import type { RepeatRangeUncontrolledNode } from './RepeatRangeUncontrolledNode.ts';
 

package/src/client/repeat/RepeatRangeUncontrolledNode.ts

@@ -1,4 +1,4 @@
-import type { UncontrolledRepeatRangeDefinition } from '../../model/RepeatRangeDefinition.ts';
+import type { UncontrolledRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
 import type { RootNode } from '../RootNode.ts';
 import type { BaseRepeatRangeNode, BaseRepeatRangeNodeState } from './BaseRepeatRangeNode.ts';
 

package/src/client/resources.ts

@@ -0,0 +1,118 @@
+import type { JRResourceURL } from '@getodk/common/jr-resources/JRResourceURL.ts';
+import type { initializeForm } from '../instance/index.ts';
+
+interface FetchResourceHeadersIterator<T>
+	extends IteratorObject<
+		T,
+		// Note: we use this weird TypeScript intrinsic type so a built-in
+		// `HeadersIterator` is assignable regardless of a client's configured
+		// TypeScript or linting strictness. We don't actually care about the type, or
+		// consume the value it represents.
+		BuiltinIteratorReturn,
+		unknown
+	> {
+	[Symbol.iterator](): FetchResourceHeadersIterator<T>;
+}
+
+type FetchResourceHeadersForEachCallbackFn = (
+	value: string,
+	key: string,
+	parent: FetchResourceResponseHeaders
+) => void;
+
+/**
+ * A read-only strict subset of the web standard {@link Headers}.
+ *
+ * Note that the engine may make the following assumptions about
+ * {@link FetchResourceResponse.headers}:
+ *
+ * - If {@link FetchResourceResponse} is an instance of {@link Response}, it
+ *   will be assumed its {@link FetchResourceResponse.headers | headers object}
+ *   _is present_, and that it is an instance of {@link Headers}. In other
+ *   words: for the purposes of resource resolution, we explicitly expect that
+ *   clients using APIs provided by the runtime platform (or polyfills thereof)
+ *   will not monkey-patch properties of values produced by those APIs.
+ *
+ * - If the object is an instance of {@link Headers} (whether by inference as a
+ *   property of {@link Response}, or by a direct instance type check), the
+ *   engine will assume it is safe to treat header names as case insensitive for
+ *   any lookups it may perform. In other words: we explicitly expect that
+ *   clients _providing access_ to APIs rovided by the runtime platform (or
+ *   polyfills thereof) will not alter the guarantees of those APIs.
+ *
+ * - If the object is not an instance of {@link Headers}, it will be treated as
+ *   a {@link ReadonlyMap<string, string>}. In other words: we explicitly expect
+ *   that clients, when providing a bespoke implementation of
+ *   {@link FetchResourceResponse} and its constituent parts, will likely
+ *   implement them partially (and in the case of
+ *   {@link FetchResourceResponse.headers}, with the nearest common idiom
+ *   available). In this case, we will favor a best effort at correctness,
+ *   generally at some expense of performance.
+ */
+export interface FetchResourceResponseHeaders {
+	[Symbol.iterator](): FetchResourceHeadersIterator<[string, string]>;
+
+	entries(): FetchResourceHeadersIterator<[string, string]>;
+	keys(): FetchResourceHeadersIterator<string>;
+	values(): FetchResourceHeadersIterator<string>;
+
+	get(name: string): string | null;
+	has(name: string): boolean;
+	forEach(callbackfn: FetchResourceHeadersForEachCallbackFn): void;
+}
+
+/**
+ * This is a strict subset of the web standard {@link Response}. Clients are
+ * encouraged to use the global {@link Response} constructor (as provided by the
+ * runtime platform, or by a global runtime polyfill), but may also provide a
+ * bespoke implementation if it suits their needs.
+ *
+ * Since we cannot assume a client's implementation will always be an instance
+ * of {@link Response}, we make some assumptions about its {@link headers}
+ * object (if available, as detailed on {@link FetchResourceResponseHeaders}).
+ *
+ * For other properties, we make the following assumptions (all of which are
+ * assumptions we would make about a platform-provided/polyfilled
+ * {@link Response}, but are explicitly stated for the benefit of confidence in
+ * client implementations):
+ *
+ * - If we read {@link body} directly, we will assume it is consumed on first
+ *   read, and will not read it again.
+ *
+ * - We assume that {@link blob} and {@link text} indirectly consume
+ *   {@link body} on first read as well, and will only ever read one of each of
+ *   these properties, and only ever once.
+ *
+ * Furthermore, if the engine intends to read {@link body} (or its indirect
+ * {@link blob} or {@link text} consumers), it will do so in the course of a
+ * client's call to {@link initializeForm}, and before the
+ * {@link Promise<PrimaryInstance>} returned by that call is resolved.
+ */
+export interface FetchResourceResponse {
+	readonly ok?: boolean;
+	readonly status?: number;
+	readonly body?: ReadableStream<Uint8Array> | null;
+	readonly bodyUsed?: boolean;
+	readonly headers?: FetchResourceResponseHeaders;
+
+	readonly blob: () => Promise<Blob>;
+	readonly text: () => Promise<string>;
+}
+
+/**
+ * This is a strict subset of the web standard `fetch` interface. It implicitly
+ * assumes that the engine itself will only ever perform `GET`-like network/IO
+ * requests. It also provides no further request-like semantics to the engine.
+ *
+ * This is presumed sufficient for now, but notably doesn't expose any notion of
+ * content negotiation (e.g. the ability for the engine to include `Accept`
+ * headers in resource requests issued to a client's {@link FetchResource}
+ * implementation).
+ */
+export type FetchResource<Resource extends URL = URL> = (
+	resource: Resource
+) => Promise<FetchResourceResponse>;
+
+export type FormAttachmentURL = JRResourceURL;
+
+export type FetchFormAttachment = FetchResource<FormAttachmentURL>;

package/src/client/submission/SubmissionData.ts

@@ -0,0 +1,12 @@
+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;
+}

package/src/client/submission/SubmissionDefinition.ts

@@ -0,0 +1,16 @@
+export interface SubmissionDefinition {
+	/**
+	 * @see {@link https://getodk.github.io/xforms-spec/#submission-attributes | `action` submission attribute}
+	 */
+	readonly submissionAction: URL | null;
+
+	/**
+	 * @see {@link https://getodk.github.io/xforms-spec/#submission-attributes | `method` submission attribute}
+	 */
+	readonly submissionMethod: 'post';
+
+	/**
+	 * @see {@link https://getodk.github.io/xforms-spec/#submission-attributes | `base64RsaPublicKey` submission attribute}
+	 */
+	readonly encryptionKey: string | null;
+}

package/src/client/submission/SubmissionInstanceFile.ts

@@ -0,0 +1,9 @@
+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;
+}

package/src/client/submission/SubmissionOptions.ts

@@ -0,0 +1,28 @@
+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];

package/src/client/submission/SubmissionResult.ts

@@ -0,0 +1,124 @@
+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];

package/src/client/submission/SubmissionState.ts

@@ -0,0 +1,14 @@
+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;
+}

package/src/client/unsupported/RangeNode.ts

@@ -0,0 +1,14 @@
+import type { RangeControlDefinition } from '../../parse/body/control/RangeControlDefinition.ts';
+import type {
+	UnsupportedControlDefinition,
+	UnsupportedControlNode,
+} from './UnsupportedControlNode.ts';
+
+export interface RangeNodeDefinition extends UnsupportedControlDefinition {
+	readonly bodyElement: RangeControlDefinition;
+}
+
+export interface RangeNode extends UnsupportedControlNode {
+	readonly nodeType: 'range';
+	readonly definition: RangeNodeDefinition;
+}

package/src/client/unsupported/RankNode.ts

@@ -0,0 +1,14 @@
+import type { RankControlDefinition } from '../../parse/body/control/RankControlDefinition.ts';
+import type {
+	UnsupportedControlDefinition,
+	UnsupportedControlNode,
+} from './UnsupportedControlNode.ts';
+
+export interface RankNodeDefinition extends UnsupportedControlDefinition {
+	readonly bodyElement: RankControlDefinition;
+}
+
+export interface RankNode extends UnsupportedControlNode {
+	readonly nodeType: 'rank';
+	readonly definition: RankNodeDefinition;
+}

package/src/client/unsupported/UnsupportedControlNode.ts

@@ -0,0 +1,40 @@
+import type { UnknownAppearanceDefinition } from '../../parse/body/appearance/unknownAppearanceParser.ts';
+import type { RangeControlDefinition } from '../../parse/body/control/RangeControlDefinition.ts';
+import type { RankControlDefinition } from '../../parse/body/control/RankControlDefinition.ts';
+import type { UploadControlDefinition } from '../../parse/body/control/UploadControlDefinition.ts';
+import type { LeafNodeDefinition } from '../../parse/model/LeafNodeDefinition.ts';
+import type { BaseNode, BaseNodeState } from '../BaseNode.ts';
+import type { RootNode } from '../RootNode.ts';
+import type { GeneralParentNode } from '../hierarchy.ts';
+import type { UnsupportedControlNodeType } from '../node-types.ts';
+import type { LeafNodeValidationState } from '../validation.ts';
+
+export interface UnsupportedControlNodeState extends BaseNodeState {
+	get children(): null;
+	get valueOptions(): unknown;
+	get value(): unknown;
+}
+
+export type UnsupportedControlElementDefinition =
+	| RangeControlDefinition
+	| RankControlDefinition
+	| UploadControlDefinition;
+
+export interface UnsupportedControlDefinition extends LeafNodeDefinition {
+	readonly bodyElement: UnsupportedControlElementDefinition;
+}
+
+/**
+ * Stub node, for form controls pending further engine support.
+ */
+export interface UnsupportedControlNode extends BaseNode {
+	readonly nodeType: UnsupportedControlNodeType;
+	readonly appearances: UnknownAppearanceDefinition;
+	readonly definition: UnsupportedControlDefinition;
+	readonly root: RootNode;
+	readonly parent: GeneralParentNode;
+	readonly currentState: UnsupportedControlNodeState;
+	readonly validationState: LeafNodeValidationState;
+
+	setValue?(value: never): never;
+}

package/src/client/unsupported/UploadNode.ts

@@ -0,0 +1,14 @@
+import type { UploadControlDefinition } from '../../parse/body/control/UploadControlDefinition.ts';
+import type {
+	UnsupportedControlDefinition,
+	UnsupportedControlNode,
+} from './UnsupportedControlNode.ts';
+
+export interface UploadNodeDefinition extends UnsupportedControlDefinition {
+	readonly bodyElement: UploadControlDefinition;
+}
+
+export interface UploadNode extends UnsupportedControlNode {
+	readonly nodeType: 'upload';
+	readonly definition: UploadNodeDefinition;
+}

package/src/client/validation.ts

@@ -1,5 +1,5 @@
-import type { NodeID } from '../instance/identity.ts';
 import type { BaseNode, BaseNodeState } from './BaseNode.ts';
+import type { FormNodeID } from './identity.ts';
 import type { OpaqueReactiveObjectFactory } from './OpaqueReactiveObjectFactory.ts';
 import type { RootNode } from './RootNode.ts';
 import type { TextRange } from './TextRange.ts';
@@ -176,7 +176,7 @@ export interface LeafNodeValidationState {
  * each property will be directly computed from the affected node.
  */
 export interface DescendantNodeViolationReference {
-	readonly nodeId: NodeID;
+	readonly nodeId: FormNodeID;
 
 	get reference(): string;
 	get violation(): AnyViolation;

package/src/error/ErrorProductionDesignPendingError.ts

@@ -0,0 +1,6 @@
+/**
+ * Temporary representation of newly introduced error conditions which we may
+ * produce to clients (and beyond). Intentionally a stub pending a more concrete
+ * design and implementation of our approach to producing Result types.
+ */
+export class ErrorProductionDesignPendingError extends Error {}

package/src/error/ValueTypeInvariantError.ts

@@ -0,0 +1,22 @@
+import type { ValueType } from '../client/ValueType.ts';
+import { ErrorProductionDesignPendingError } from './ErrorProductionDesignPendingError.ts';
+
+/**
+ * Temporary(?) representation of error conditions arising from violation of
+ * invariants specific to {@link valueType}.
+ *
+ * @todo The intent of this distinct subclass of
+ * {@link ErrorProductionDesignPendingError} is to call out cases where we may
+ * want to represent such errors to clients as **validation errors** in the
+ * future. We identified this as probably desirable in the initial work on `int`
+ * and `decimal` value types, but held off on that aspect of implementation to
+ * tame scope.
+ */
+export class ValueTypeInvariantError extends ErrorProductionDesignPendingError {
+	constructor(
+		readonly valueType: ValueType,
+		message: string
+	) {
+		super(`(${valueType}) ${message}`);
+	}
+}