@honua/app-platform 0.1.2-beta.0 → 0.1.4-beta.0

package/web-components/feature-editor-workflow.js

@@ -0,0 +1,889 @@
+/**
+ * Host-facing edit workflow behind `<honua-feature-editor>` (issue #680).
+ *
+ * This is the composition layer: it owns a public contract
+ * {@link EditSketchWorkflowModel} (which itself owns the edit session, undo /
+ * redo, snapping, attachment staging, optimistic hooks, and the single
+ * `applyEdits` call) and adds only what an operational editing UI needs on top
+ * and the protocol layer deliberately does not model:
+ *
+ * - **Draft identity.** A draft is scoped to `source` + feature id + the
+ *   concurrency token observed when it opened, so an unrelated realtime change
+ *   can be recognised and ignored without disturbing the form
+ *   ({@link HonuaFeatureEditorWorkflow.applyExternalChange}, REQ-005).
+ * - **Subtype-aware pre-transport validation.** Subtype overrides change the
+ *   valid choices per field. Rather than duplicating the contract validator,
+ *   {@link HonuaFeatureEditorWorkflow.validate} builds a throwaway
+ *   `createEditSession` over the *subtype-resolved* field list and runs the
+ *   contract's own `validate()` against it, merging the result with the live
+ *   model's session-level verdict. An invalid draft is rejected with
+ *   `transported: false` — nothing reaches the wire.
+ * - **An explicit conflict gate.** A version/etag/precondition failure (or a
+ *   divergent external change) parks the draft in `"conflict"`; `submit()`
+ *   refuses to retransport until {@link HonuaFeatureEditorWorkflow.resolveConflict}
+ *   records a decision (REQ-004 / REQ-005).
+ * - **Redacted state.** Snapshots and events describe staged attachments but
+ *   never carry the payload — a `Blob` or a (possibly credential-bearing)
+ *   string URL stays inside the edit session.
+ *
+ * No protocol adapter is imported and no status is ever optimistic about a
+ * rejected edit: every non-`"succeeded"` submit result maps to
+ * `"rejected"` / `"conflict"` / `"unsupported"` / `"cancelled"`, never
+ * `"committed"`.
+ *
+ * @module
+ */
+import { createEditSession, } from "../contract/edit-session.js";
+import { createEditSketchWorkflow, } from "../contract/edit-sketch.js";
+import { buildEditorFormModel, coerceEditorFieldValue, editorFieldsFromSchema, editorOperationAvailability, redactEditorAttachment, resolveActiveEditorSubtype, resolveEditorFields, resolveEditorOperations, } from "./feature-editor-model.js";
+const EMPTY_UNDO = { canUndo: false, canRedo: false, undoDepth: 0, redoDepth: 0 };
+const CONFLICT_CHOICES = ["keep-mine", "discard-mine", "reload"];
+export class HonuaFeatureEditorWorkflow {
+    source;
+    #options;
+    #listeners = new Set();
+    #schemaFields;
+    #sketchTools;
+    #model;
+    #selection;
+    #operation;
+    #status = "idle";
+    #identity;
+    #baseline;
+    #failures = [];
+    #attachments = [];
+    #conflict;
+    #message = "";
+    #committedFeatureId;
+    #abort;
+    /**
+     * The model whose in-flight submit was cancelled. Identity, not a boolean:
+     * `AbortSignal` is advisory — a transport may ignore it and settle anyway —
+     * so a completion has to prove it still owns the workflow before touching
+     * shared state.
+     */
+    #cancelledModel;
+    constructor(options) {
+        this.source = options.source;
+        this.#options = options;
+        this.#sketchTools = options.sketchTools;
+        this.#schemaFields = resolveSchemaFields(options);
+        this.#message = "Pick an operation to start editing.";
+    }
+    // ── subscription ───────────────────────────────────────────────────────
+    /** Subscribes to snapshot changes. Mirrors the kit's `{ remove() }` idiom. */
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return {
+            remove: () => {
+                this.#listeners.delete(listener);
+            },
+        };
+    }
+    // ── inspection ─────────────────────────────────────────────────────────
+    /** The underlying contract sketch workflow, for a sketch adapter to bind to. */
+    sketchModel() {
+        return this.#model;
+    }
+    /**
+     * Subtype-resolved field metadata for the open draft, or — before one is
+     * opened — for the recorded selection. Resolving against the selection
+     * matters: a subtype's overrides can flip a field's editability, so using the
+     * default subtype here would report the wrong `update` / `delete`
+     * availability for the feature the host actually selected.
+     */
+    fields() {
+        return this.#fieldsFor(this.#values());
+    }
+    /** Truthful per-operation availability for the current source and selection. */
+    operations() {
+        return this.#operationsFor(this.#values());
+    }
+    /**
+     * Merged pre-transport validation: the contract validator run over the
+     * subtype-resolved field list, unioned with the live session's own
+     * session-level verdict (capability, identity, attachment support).
+     */
+    validate() {
+        const model = this.#model;
+        if (!model || !this.#operation) {
+            return { valid: false, errors: [{ code: "required", message: "No edit draft is open." }] };
+        }
+        const sessionErrors = model.validate().errors;
+        const derivedErrors = createEditSession({
+            source: this.source,
+            kind: this.#operation,
+            ...(this.#baseline ? { feature: this.#baseline } : {}),
+            values: this.#values(),
+            metadata: { fields: this.fields() },
+        }).validate().errors;
+        const errors = dedupeValidationErrors([...sessionErrors, ...derivedErrors]);
+        return { valid: errors.length === 0, errors };
+    }
+    /** Current UI state. Never contains an attachment payload. */
+    snapshot() {
+        const model = this.#model;
+        const sketch = model?.snapshot().sketch;
+        return {
+            status: this.#status,
+            ...(this.#operation ? { operation: this.#operation } : {}),
+            ...(this.#identity ? { identity: this.#identity } : {}),
+            operations: this.operations(),
+            ...(model && this.#operation
+                ? {
+                    form: buildEditorFormModel({
+                        operation: this.#operation,
+                        fields: this.fields(),
+                        values: this.#values(),
+                        validation: this.validate(),
+                        ...(this.#options.subtypes ? { subtypes: this.#options.subtypes } : {}),
+                    }),
+                }
+                : {}),
+            ...(sketch
+                ? {
+                    sketch: {
+                        status: sketch.status,
+                        ...(sketch.activeTool ? { activeTool: sketch.activeTool } : {}),
+                        tools: sketch.tools,
+                        geometry: sketch.geometry,
+                        snapping: { enabled: sketch.snapping.enabled, tolerance: sketch.snapping.tolerance },
+                    },
+                }
+                : {}),
+            undo: model?.snapshot().undo ?? EMPTY_UNDO,
+            attachments: this.#attachments,
+            attachmentsSupported: this.source.capabilities.has("attachments"),
+            failures: this.#failures,
+            ...(this.#conflict ? { conflict: this.#conflict } : {}),
+            dirty: model?.dirty() ?? false,
+            busy: this.#status === "submitting",
+            message: this.#message,
+            ...(this.#committedFeatureId !== undefined ? { committedFeatureId: this.#committedFeatureId } : {}),
+        };
+    }
+    // ── draft lifecycle ────────────────────────────────────────────────────
+    /**
+     * Records the host's current selection (table row, map click, search result)
+     * so `update` / `delete` availability reflects it before a draft is opened.
+     *
+     * Ignored while a draft is open — an open draft owns its identity. A
+     * *committed* draft is the one exception: it is finished, and the host's
+     * re-read of the record it just wrote carries the only fresh concurrency
+     * token there is. Refusing it would leave `selection()` on the pre-commit
+     * feature, so the next `update` would reopen on a stale token the service has
+     * to reject. Accepting it closes the finished draft without touching the
+     * committed status or message — nothing about the commit is retracted.
+     */
+    setSelection(feature) {
+        if (this.#model && this.#status !== "committed")
+            return this.snapshot();
+        if (this.#model) {
+            this.#model = undefined;
+            this.#operation = undefined;
+            this.#baseline = undefined;
+            this.#attachments = [];
+        }
+        this.#selection = feature ? cloneFeature(feature) : undefined;
+        this.#identity = this.#identityFor(feature);
+        return this.#notify();
+    }
+    /** The host selection `update` / `delete` drafts open on. */
+    selection() {
+        return this.#selection;
+    }
+    /**
+     * Opens a draft, defaulting to the recorded selection. When the requested
+     * operation is not truthfully available the draft is refused and the reason
+     * recorded — never silently downgraded.
+     */
+    begin(operation, feature) {
+        const target = operation === "create" ? feature : (feature ?? this.#selection);
+        this.#abort?.abort();
+        // Any in-flight submit now belongs to a superseded draft, cancelled or not.
+        this.#cancelledModel = undefined;
+        this.#conflict = undefined;
+        this.#failures = [];
+        this.#attachments = [];
+        this.#committedFeatureId = undefined;
+        this.#identity = this.#identityFor(target);
+        // Resolve availability against the feature this draft would open on, not
+        // the standing selection — an explicit `feature` argument may carry a
+        // different subtype, and subtypes can flip field editability.
+        const availability = editorOperationAvailability(this.#operationsFor((target?.attributes ?? {})), operation);
+        if (!availability.available) {
+            this.#model = undefined;
+            this.#operation = undefined;
+            this.#status = isCapabilityGate(availability.code) ? "unsupported" : "rejected";
+            this.#message = availability.reason ?? `${operation} is not available for this source.`;
+            this.#failures = [
+                {
+                    kind: isCapabilityGate(availability.code) ? "capability" : "validation",
+                    operation: "session",
+                    description: this.#message,
+                },
+            ];
+            return this.#notify();
+        }
+        this.#operation = operation;
+        this.#baseline = target ? cloneFeature(target) : undefined;
+        this.#model = this.#createModel(operation, target);
+        if (operation === "create")
+            this.#seedCreateDefaults();
+        this.#status = "draft";
+        this.#message = draftMessage(operation);
+        return this.#notify();
+    }
+    /** Discards the draft and aborts any in-flight submit. */
+    cancel() {
+        if (this.#status === "submitting")
+            this.#cancelledModel = this.#model;
+        this.#abort?.abort();
+        this.#abort = undefined;
+        this.#model = undefined;
+        this.#operation = undefined;
+        this.#baseline = undefined;
+        this.#conflict = undefined;
+        this.#failures = [];
+        this.#attachments = [];
+        this.#status = "cancelled";
+        this.#message = "Edit cancelled. Nothing was sent to the service.";
+        return this.#notify();
+    }
+    /** Reverts the draft to the feature it opened on, keeping the draft open. */
+    discardChanges() {
+        this.#model?.discard();
+        this.#attachments = [];
+        this.#failures = [];
+        this.#conflict = undefined;
+        if (this.#model)
+            this.#status = "draft";
+        this.#message = "Draft reverted to the last known server values.";
+        return this.#notify();
+    }
+    // ── attribute editing ──────────────────────────────────────────────────
+    /**
+     * Records raw control input for a field, coerced to the field's own type
+     * (coded values resolve back to the domain code's type, so a numeric code
+     * never reaches transport as a string).
+     */
+    setValue(name, raw) {
+        const model = this.#model;
+        if (!model)
+            return this.snapshot();
+        const field = this.fields().find((entry) => entry.name === name) ?? { name };
+        model.setValue(name, coerceEditorFieldValue(field, raw));
+        this.#afterEdit();
+        return this.#notify();
+    }
+    /** Records several already-typed attribute values at once. */
+    setValues(values) {
+        const model = this.#model;
+        if (!model)
+            return this.snapshot();
+        model.setValues(values);
+        this.#afterEdit();
+        return this.#notify();
+    }
+    // ── geometry ───────────────────────────────────────────────────────────
+    /** Arms a sketch tool. Unsupported tools report their reason rather than throwing. */
+    startSketch(tool) {
+        const model = this.#model;
+        if (!model)
+            return { tool, state: "unsupported", reason: "No edit draft is open." };
+        const capability = model.startSketch(tool);
+        this.#message =
+            capability.state === "supported"
+                ? `Sketching a ${tool}. Enter coordinates or draw on the map.`
+                : (capability.reason ?? `The ${tool} tool is not available.`);
+        this.#notify();
+        return capability;
+    }
+    /** Applies a geometry through the sketch workflow (undoable). */
+    setGeometry(tool, geometry) {
+        const model = this.#model;
+        if (!model)
+            return this.snapshot();
+        model.setSketchGeometry(tool, geometry);
+        this.#afterEdit();
+        return this.#notify();
+    }
+    undo() {
+        const undone = this.#model?.undo() ?? false;
+        if (undone) {
+            this.#afterEdit();
+            this.#notify();
+        }
+        return undone;
+    }
+    redo() {
+        const redone = this.#model?.redo() ?? false;
+        if (redone) {
+            this.#afterEdit();
+            this.#notify();
+        }
+        return redone;
+    }
+    // ── attachments ────────────────────────────────────────────────────────
+    /**
+     * Stages an attachment. The payload is handed straight to the edit session;
+     * only redacted metadata enters the snapshot.
+     */
+    stageAttachment(attachment, options = {}) {
+        const model = this.#model;
+        if (!model)
+            return this.snapshot();
+        model.stageAttachmentAdd(attachment, options);
+        this.#syncAttachmentDrafts();
+        this.#afterEdit();
+        return this.#notify();
+    }
+    /** Stages an attachment deletion. */
+    stageAttachmentDelete(attachmentIds, options = {}) {
+        const model = this.#model;
+        if (!model)
+            return this.snapshot();
+        model.stageAttachmentDelete(attachmentIds, options);
+        this.#syncAttachmentDrafts();
+        this.#afterEdit();
+        return this.#notify();
+    }
+    // ── sketch adapter seam ────────────────────────────────────────────────
+    /**
+     * Replaces the sketch tool capabilities (a sketch adapter such as terra-draw
+     * calls this so `rectangle` / `circle` become truthfully supported). An open
+     * draft is rebuilt in place, preserving values, geometry, and staged
+     * attachments; undo history restarts because tool support is a new baseline.
+     */
+    configureSketchTools(tools) {
+        // Idempotent: re-declaring the same tool support must not rebuild an open
+        // draft (a sketch adapter may re-announce it on every attach).
+        if (JSON.stringify(this.#sketchTools ?? null) === JSON.stringify(tools))
+            return this.snapshot();
+        this.#sketchTools = tools;
+        const model = this.#model;
+        // Never swap the model out from under an in-flight submit: that would make
+        // the pending completion look superseded and silently drop its outcome.
+        // The new tool support applies to the next draft instead.
+        if (model && this.#operation && this.#status !== "submitting") {
+            const snapshot = model.snapshot();
+            this.#model = this.#createModel(this.#operation, snapshot.feature);
+            for (const mutation of snapshot.attachments)
+                restageAttachment(this.#model, mutation);
+        }
+        return this.#notify();
+    }
+    // ── submit ─────────────────────────────────────────────────────────────
+    /**
+     * Validates, then applies the draft through the contract edit session.
+     *
+     * Refuses to transport when the draft is invalid or an unresolved conflict is
+     * parked (`transported: false`). Every non-success result maps to a
+     * rejected / conflict / unsupported state — never `"committed"`.
+     */
+    async submit() {
+        const model = this.#model;
+        const operation = this.#operation;
+        if (!model || !operation) {
+            return this.#preflightRejection("create", "No edit draft is open.", "validation");
+        }
+        if (this.#conflict) {
+            return this.#preflightRejection(operation, "Resolve the conflicting change before submitting again.", "conflict", "conflict");
+        }
+        const validation = this.validate();
+        if (!validation.valid) {
+            this.#status = validation.errors.some((error) => error.code === "unsupported") ? "unsupported" : "rejected";
+            this.#failures = validation.errors.map((error) => ({
+                kind: error.code === "unsupported" ? "capability" : "validation",
+                operation: "session",
+                description: error.message,
+            }));
+            this.#message = "The draft was not sent: fix the highlighted problems first.";
+            return this.#commit(operation, false);
+        }
+        this.#status = "submitting";
+        this.#failures = [];
+        this.#message = `Applying the ${operation}…`;
+        this.#notify();
+        const result = await model.submit();
+        // An `AbortSignal` is advisory: a transport may settle a cancelled — or
+        // superseded — submit anyway. Before touching shared state, prove this
+        // completion still owns the workflow. Otherwise a slow first submit could
+        // stamp its own outcome (and identity, baseline, and message) onto a draft
+        // that was opened after it started.
+        const cancelledThisSubmit = this.#cancelledModel === model;
+        if (cancelledThisSubmit)
+            this.#cancelledModel = undefined;
+        if (this.#model !== model) {
+            // `begin()` clears `#cancelledModel`, so reaching here with it still set
+            // means the cancel was the last thing to touch the workflow.
+            if (cancelledThisSubmit && this.#model === undefined) {
+                this.#message = "Edit cancelled while it was being applied; treat the outcome as unknown.";
+                this.#failures = result.failures.map(normalizeFailure);
+                return this.#commit(operation, true);
+            }
+            return this.#supersededCommit(operation, model, result);
+        }
+        this.#failures = result.failures.map(normalizeFailure);
+        this.#attachments = attachmentDraftsFromResult(model, result.attachmentResults);
+        const conflictFailure = result.failures.find((failure) => failure.kind === "conflict");
+        if (result.status === "succeeded") {
+            this.#status = "committed";
+            this.#committedFeatureId = result.committedFeatureId;
+            this.#identity = this.#identityAfterCommit(result.committedFeatureId);
+            this.#baseline = cloneFeature(model.snapshot().feature);
+            this.#message = committedMessage(operation, result.committedFeatureId);
+        }
+        else if (conflictFailure || result.conflict) {
+            const info = conflictFailure?.conflict ?? result.conflict;
+            this.#status = "conflict";
+            this.#conflict = conflictFrom(info, this.#identity, conflictFailure?.description);
+            this.#message = "Someone else changed this feature. Choose how to resolve it.";
+        }
+        else if (result.status === "unsupported") {
+            this.#status = "unsupported";
+            this.#message = result.failures[0]?.description ?? "This source does not support the requested edit.";
+        }
+        else if (result.status === "partial") {
+            this.#status = "rejected";
+            this.#message = "The edit only partly applied. Review the failures before retrying.";
+        }
+        else {
+            this.#status = "rejected";
+            this.#message = result.failures[0]?.description ?? "The service rejected the edit.";
+        }
+        return this.#commit(operation, true);
+    }
+    /** Re-submits after a rejection (or after a resolved conflict). */
+    async retry() {
+        if (this.#status === "submitting") {
+            return this.#preflightRejection(this.#operation ?? "create", "An edit is already in flight.", "validation");
+        }
+        if (this.#status !== "conflict")
+            this.#status = "draft";
+        return this.submit();
+    }
+    // ── conflict resolution ────────────────────────────────────────────────
+    /**
+     * Records an explicit decision for a parked conflict.
+     *
+     * - `"keep-mine"` keeps the draft and, when the source's concurrency token
+     *   is known, adopts the observed server token so the retry can pass the
+     *   service's precondition (an explicit overwrite).
+     * - `"discard-mine"` reverts the draft to the feature it opened on.
+     * - `"reload"` closes the draft; the host is expected to reopen it on fresh
+     *   server state.
+     */
+    resolveConflict(choice) {
+        const conflict = this.#conflict;
+        if (!conflict)
+            return this.snapshot();
+        if (choice === "reload") {
+            this.#conflict = undefined;
+            this.#model = undefined;
+            this.#operation = undefined;
+            this.#baseline = undefined;
+            this.#status = "idle";
+            this.#message = "Reload the feature to continue editing the current server version.";
+            return this.#notify();
+        }
+        if (choice === "discard-mine") {
+            this.#conflict = undefined;
+            this.#model?.discard();
+            this.#status = this.#model ? "draft" : "idle";
+            this.#message = "Your changes were discarded; the draft matches the last known server values.";
+            this.#failures = [];
+            return this.#notify();
+        }
+        this.#conflict = undefined;
+        if (conflict.versionField !== undefined && conflict.theirs !== undefined) {
+            this.#model?.setValue(conflict.versionField, conflict.theirs);
+            if (this.#identity)
+                this.#identity = { ...this.#identity, version: conflict.theirs };
+        }
+        this.#status = "draft";
+        this.#failures = [];
+        this.#message = "Keeping your changes. Submitting again will overwrite the other edit.";
+        return this.#notify();
+    }
+    /**
+     * Adopts the service's post-write concurrency token into a draft that stays
+     * open on purpose — the partial outcome where the feature edit applied and
+     * only an attachment was refused (issue #680).
+     *
+     * A protocol like GeoServices returns nothing but `objectId` and `success`
+     * from `applyEdits`, so the new token exists only in the host's re-read of the
+     * record. Feeding that back through {@link setValue} would read as a user
+     * revision and clear the rejected status and the recorded failures — erasing
+     * exactly the truth about what the service refused. This does not: status,
+     * failures, and staged-attachment outcomes all survive, so {@link retry}
+     * re-transports the same recovery against the version now on file instead of
+     * the one the accepted write already consumed.
+     *
+     * The draft's own baseline is deliberately left alone: it is still the values
+     * this draft opened on, and moving it could make an unrelated server-assigned
+     * field look like a read-only edit the user made.
+     *
+     * Returns `false` — changing nothing — when no draft is open, when the record
+     * is a different feature, or when the source publishes no concurrency token.
+     */
+    adoptServerState(feature) {
+        const model = this.#model;
+        const identity = this.#identity;
+        if (!model || identity?.featureId === undefined)
+            return false;
+        if (feature.id === undefined || String(feature.id) !== String(identity.featureId))
+            return false;
+        const field = identity.versionField;
+        if (field === undefined)
+            return false;
+        const token = feature.attributes[field];
+        if (token === undefined)
+            return false;
+        model.setValue(field, token);
+        this.#identity = { ...identity, version: token };
+        this.#notify();
+        return true;
+    }
+    // ── realtime reconciliation ────────────────────────────────────────────
+    /**
+     * Reconciles one externally changed feature against the open draft (REQ-005).
+     *
+     * - A change to a different feature is `"ignored"`: no state changes and no
+     *   listener runs, so selection, unsaved values, focus, and geometry survive
+     *   unrelated realtime traffic untouched.
+     * - A change to the drafted feature carrying the same concurrency token is
+     *   `"reconciled"`: the baseline adopts the server values, and only fields the
+     *   user has *not* touched adopt the new values.
+     * - A change carrying a different token is a `"conflict"`: the draft is
+     *   untouched and parked until {@link resolveConflict} records a decision.
+     */
+    applyExternalChange(feature) {
+        const model = this.#model;
+        const identity = this.#identity;
+        if (!model || identity === undefined || identity.featureId === undefined)
+            return "ignored";
+        if (feature.id === undefined || String(feature.id) !== String(identity.featureId))
+            return "ignored";
+        const conflictInfo = model.snapshot().metadata.conflict;
+        const theirs = tokenOf(feature, conflictInfo);
+        const mine = identity.version;
+        if (theirs !== undefined && mine !== undefined && String(theirs) !== String(mine)) {
+            this.#conflict = {
+                reason: "The feature changed on the server while this draft was open.",
+                ...(identity.versionField ? { versionField: identity.versionField } : {}),
+                mine,
+                theirs,
+                choices: CONFLICT_CHOICES,
+            };
+            this.#status = "conflict";
+            this.#message = "Someone else changed this feature. Choose how to resolve it.";
+            this.#notify();
+            return "conflict";
+        }
+        const baseline = this.#baseline;
+        const current = model.snapshot().feature.attributes;
+        const incoming = feature.attributes;
+        const untouched = {};
+        for (const [name, value] of Object.entries(incoming)) {
+            const previous = baseline?.attributes?.[name];
+            if (sameScalar(current[name], previous))
+                untouched[name] = value;
+        }
+        this.#baseline = cloneFeature(feature);
+        if (Object.keys(untouched).length > 0)
+            model.setValues(untouched);
+        if (theirs !== undefined)
+            this.#identity = { ...identity, version: theirs };
+        this.#message = "Adopted the latest server values for fields you have not changed.";
+        this.#notify();
+        return "reconciled";
+    }
+    // ── internals ──────────────────────────────────────────────────────────
+    #createModel(operation, feature) {
+        this.#abort = new AbortController();
+        return createEditSketchWorkflow({
+            source: this.source,
+            kind: operation,
+            ...(feature ? { feature: cloneFeature(feature) } : {}),
+            metadata: {
+                fields: this.#baseFields(),
+                ...(this.#options.metadata?.primaryKey ? { primaryKey: this.#options.metadata.primaryKey } : {}),
+                ...(this.#options.metadata?.relationships ? { relationships: this.#options.metadata.relationships } : {}),
+                ...(this.#options.metadata?.conflict ? { conflict: this.#options.metadata.conflict } : {}),
+            },
+            ...(this.#sketchTools ? { sketchTools: this.#sketchTools } : {}),
+            ...(this.#options.snapping ? { snapping: this.#options.snapping } : {}),
+            ...(this.#options.rollbackOnFailure !== undefined ? { rollbackOnFailure: this.#options.rollbackOnFailure } : {}),
+            ...(this.#options.optimistic ? { optimistic: this.#options.optimistic } : {}),
+            signal: this.#abort.signal,
+        });
+    }
+    /**
+     * Field list the long-lived session validates against: subtype *domain* but
+     * no per-subtype overrides, so the session never rejects a value the active
+     * subtype allows. Subtype-specific rules are enforced by {@link validate}
+     * over the resolved list before anything is transported.
+     */
+    #baseFields() {
+        const subtypes = this.#options.subtypes;
+        return resolveEditorFields(this.#schemaFields, subtypes ? { field: subtypes.field, subtypes: subtypes.subtypes } : undefined, {});
+    }
+    #seedCreateDefaults() {
+        const subtypes = this.#options.subtypes;
+        if (!subtypes || subtypes.defaultCode === undefined)
+            return;
+        const active = resolveActiveEditorSubtype(subtypes, {});
+        this.#model?.setValues({ [subtypes.field]: active?.code ?? subtypes.defaultCode });
+    }
+    /**
+     * Attribute values subtype resolution runs against: the open draft's, or the
+     * recorded selection's while no draft is open.
+     */
+    #values() {
+        const model = this.#model;
+        if (model)
+            return model.snapshot().feature.attributes;
+        return (this.#selection?.attributes ?? {});
+    }
+    #fieldsFor(values) {
+        return resolveEditorFields(this.#schemaFields, this.#options.subtypes, values);
+    }
+    #operationsFor(values) {
+        return resolveEditorOperations({
+            capabilities: { applyEdits: this.source.capabilities.has("applyEdits") ? "supported" : "unsupported" },
+            ...(capabilityDecisions(this.source) ? { decisions: capabilityDecisions(this.source) } : {}),
+            hasFeatureIdentity: this.#identity?.featureId !== undefined,
+            fields: this.#fieldsFor(values),
+            ...(this.#options.operations ? { overrides: this.#options.operations } : {}),
+        });
+    }
+    #identityFor(feature) {
+        const conflict = conflictInfoFor(this.source, this.#schemaFields, feature, this.#options.metadata);
+        const token = feature ? tokenOf(feature, conflict) : undefined;
+        return {
+            sourceId: this.source.descriptor.id,
+            ...(feature?.id !== undefined ? { featureId: feature.id } : {}),
+            ...(token !== undefined ? { version: token } : {}),
+            ...(conflictFieldName(conflict) ? { versionField: conflictFieldName(conflict) } : {}),
+        };
+    }
+    #identityAfterCommit(committedFeatureId) {
+        const identity = this.#identity;
+        if (!identity)
+            return undefined;
+        const model = this.#model;
+        const conflict = model?.snapshot().metadata.conflict;
+        const token = model && conflict ? tokenOf(model.snapshot().feature, conflict) : identity.version;
+        return {
+            ...identity,
+            ...(committedFeatureId !== undefined ? { featureId: committedFeatureId } : {}),
+            ...(token !== undefined ? { version: token } : {}),
+        };
+    }
+    #afterEdit() {
+        if (this.#status === "committed" || this.#status === "rejected" || this.#status === "cancelled") {
+            this.#status = "draft";
+            this.#failures = [];
+            this.#message = draftMessage(this.#operation ?? "update");
+        }
+    }
+    #syncAttachmentDrafts() {
+        const model = this.#model;
+        if (!model)
+            return;
+        this.#attachments = model
+            .snapshot()
+            .attachments.map((mutation, index) => redactEditorAttachment(mutation, index, "staged"));
+    }
+    #preflightRejection(operation, description, kind, status = "rejected") {
+        this.#status = status;
+        this.#failures = [{ kind, operation: "session", description }];
+        this.#message = description;
+        this.#notify();
+        return {
+            status: this.#status,
+            operation,
+            transported: false,
+            failures: this.#failures,
+            attachments: this.#attachments,
+            snapshot: this.snapshot(),
+        };
+    }
+    /**
+     * Result of a submit that no longer owns the workflow. Built entirely from
+     * the caller's own locals — shared state belongs to the newer draft and is
+     * deliberately left untouched, and no listener is notified.
+     */
+    #supersededCommit(operation, model, result) {
+        return {
+            status: "cancelled",
+            operation,
+            transported: true,
+            superseded: true,
+            failures: result.failures.map(normalizeFailure),
+            attachments: attachmentDraftsFromResult(model, result.attachmentResults),
+            snapshot: this.snapshot(),
+        };
+    }
+    #commit(operation, transported) {
+        const snapshot = this.#notify();
+        return {
+            status: this.#status,
+            operation,
+            transported,
+            ...(this.#committedFeatureId !== undefined && this.#status === "committed"
+                ? { committedFeatureId: this.#committedFeatureId }
+                : {}),
+            failures: this.#failures,
+            attachments: this.#attachments,
+            snapshot,
+        };
+    }
+    #notify() {
+        const snapshot = this.snapshot();
+        for (const listener of [...this.#listeners])
+            listener(snapshot);
+        return snapshot;
+    }
+}
+/** Creates a {@link HonuaFeatureEditorWorkflow}. */
+export function createFeatureEditorWorkflow(options) {
+    return new HonuaFeatureEditorWorkflow(options);
+}
+// ── module helpers ───────────────────────────────────────────────────────
+function resolveSchemaFields(options) {
+    const declared = options.metadata?.fields;
+    const fields = declared ?? editorFieldsFromSchema(options.source.descriptor.schema?.fields);
+    const domains = options.metadata?.domains;
+    if (!domains)
+        return fields;
+    return fields.map((field) => field.domain || !domains[field.name] ? field : { ...field, domain: domains[field.name] });
+}
+function capabilityDecisions(source) {
+    // The evaluated profile may live on the capability-aware source, on its
+    // descriptor, or nowhere at all; only the coarse capability set is guaranteed.
+    const carrier = source;
+    const entries = (carrier.capabilityProfile ?? carrier.descriptor?.capabilityProfile)?.entries;
+    if (!entries)
+        return undefined;
+    return entries;
+}
+function isCapabilityGate(code) {
+    return (code === "capability-unsupported" ||
+        code === "capability-unknown" ||
+        code === "authorization-required" ||
+        code === "authorization-denied" ||
+        code === "policy-disabled" ||
+        code === "peer-unavailable");
+}
+function conflictInfoFor(source, fields, feature, metadata) {
+    // Reuse the contract's own conflict inference rather than re-deriving which
+    // field carries the concurrency token.
+    const session = createEditSession({
+        source,
+        kind: feature?.id === undefined ? "create" : "update",
+        ...(feature ? { feature } : {}),
+        metadata: { fields, ...(metadata?.conflict ? { conflict: metadata.conflict } : {}) },
+    });
+    return session.metadata().conflict;
+}
+function conflictFieldName(conflict) {
+    return conflict.versionField ?? conflict.etagField ?? conflict.updatedAtField;
+}
+function tokenOf(feature, conflict) {
+    const attributes = feature.attributes;
+    const field = conflictFieldName(conflict);
+    return field ? attributes[field] : undefined;
+}
+function conflictFrom(info, identity, description) {
+    const field = info ? conflictFieldName(info) : identity?.versionField;
+    return {
+        reason: info?.reason ?? description ?? "The service reported a version conflict.",
+        ...(field ? { versionField: field } : {}),
+        ...(identity?.version !== undefined ? { mine: identity.version } : {}),
+        ...(info?.value !== undefined && String(info.value) !== String(identity?.version) ? { theirs: info.value } : {}),
+        choices: CONFLICT_CHOICES,
+    };
+}
+function normalizeFailure(failure) {
+    return {
+        kind: failure.kind,
+        operation: failure.operation,
+        ...(failure.code !== undefined ? { code: failure.code } : {}),
+        description: failure.description,
+    };
+}
+function attachmentDraftsFromResult(model, results) {
+    const staged = model.snapshot().attachments;
+    return results.map((result) => {
+        const mutation = staged[result.index] ?? { operation: result.operation };
+        const failure = result.outcomes.find((outcome) => !outcome.success);
+        if (!failure)
+            return redactEditorAttachment(mutation, result.index, "applied");
+        const skipped = failure.error?.code === 409 && failure.error.description.includes("skipped");
+        return redactEditorAttachment(mutation, result.index, skipped ? "skipped" : "failed", failure.error?.description ?? "The attachment was rejected.");
+    });
+}
+function restageAttachment(model, mutation) {
+    const options = {
+        ...(mutation.parentId !== undefined ? { parentId: mutation.parentId } : {}),
+        ...(mutation.name !== undefined ? { name: mutation.name } : {}),
+        ...(mutation.contentType !== undefined ? { contentType: mutation.contentType } : {}),
+    };
+    if (mutation.operation === "add" && mutation.attachment !== undefined) {
+        model.stageAttachmentAdd(mutation.attachment, options);
+        return;
+    }
+    if (mutation.operation === "update" && mutation.attachment !== undefined && mutation.attachmentId !== undefined) {
+        model.stageAttachmentUpdate(mutation.attachmentId, mutation.attachment, options);
+        return;
+    }
+    if (mutation.operation === "delete" && mutation.attachmentIds) {
+        model.stageAttachmentDelete(mutation.attachmentIds, options);
+    }
+}
+function dedupeValidationErrors(errors) {
+    const seen = new Set();
+    const out = [];
+    for (const error of errors) {
+        const key = `${error.code}|${error.fieldName ?? ""}|${error.message}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(error);
+    }
+    return out;
+}
+function draftMessage(operation) {
+    if (operation === "create")
+        return "New feature draft. Complete the required fields, then submit.";
+    if (operation === "delete")
+        return "Deleting this feature. Submit to confirm.";
+    return "Editing the selected feature. Submit to apply your changes.";
+}
+function committedMessage(operation, id) {
+    if (operation === "delete")
+        return "Feature deleted.";
+    const suffix = id === undefined ? "" : ` (id ${String(id)})`;
+    return operation === "create" ? `Feature created${suffix}.` : `Feature updated${suffix}.`;
+}
+function cloneFeature(feature) {
+    return {
+        ...(feature.id !== undefined ? { id: feature.id } : {}),
+        attributes: { ...feature.attributes },
+        ...(feature.geometry !== undefined ? { geometry: feature.geometry === null ? null : { ...feature.geometry } } : {}),
+    };
+}
+function sameScalar(left, right) {
+    if (Object.is(left, right))
+        return true;
+    if (left === undefined || right === undefined)
+        return left === right;
+    if (left === null || right === null)
+        return left === right;
+    if (typeof left === "object" || typeof right === "object") {
+        return JSON.stringify(left) === JSON.stringify(right);
+    }
+    return String(left) === String(right);
+}