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

package/web-components/export-redaction.js

@@ -39,239 +39,17 @@
  *
  * @module
  */
-import { HonuaSdkError } from "../core/error-envelope.js";
+import { assertCredentialFreeExportText, containsCredentialMaterial, projectExportEndpoint, redactHonuaExportText, } from "../core/credential-redaction.js";
 /** Schema id stamped on every sanitized state document. */
 export const HONUA_EXPORT_STATE_SCHEMA = "honua.app-platform.export-state.v1";
-/** Placeholder substituted for any value the export pipeline refuses to emit. */
-export const HONUA_EXPORT_REDACTED = "[REDACTED]";
-/** Thrown when the export pipeline cannot produce a provably credential-free artifact. */
-export class HonuaExportSafetyError extends HonuaSdkError {
-    reason;
-    constructor(message, reason = "assertion") {
-        super("app.export-unsafe", message);
-        this.name = "HonuaExportSafetyError";
-        this.reason = reason;
-    }
-}
-// ── credential recognition ───────────────────────────────────────────────
-/**
- * Property names that are never exported, whatever their value. Matched
- * case-insensitively against the whole key (substring match), so `apiKey`,
- * `X-API-KEY`, `refresh_token`, and `sessionCookie` are all caught.
- */
-const SENSITIVE_KEY = /(?:api[-_]?key|auth|bearer|cookie|credential|cred(?:s)?\b|jwt|nonce|pass(?:word|wd)?|private[-_]?key|pwd|secret|session|sig(?:nature)?|subscription[-_]?key|token)/i;
-/** Property names that leak *authorization scope* rather than the secret itself. */
-const AUTHORIZATION_SCOPE_KEY = /(?:^|[-_.])(?:scope|scopes|audience|aud|tenant|tenant[-_]?id|client[-_]?id|grant|grant[-_]?type|roles|permissions|principal|subject|assume[-_]?role)(?:$|[-_.])/i;
-/** Query-parameter names that make a URL a *signed* URL (presigned S3/GCS/SAS/Esri/CDN). */
-const SIGNED_QUERY_NAME = /(?:^|[-_])(?:sig|signature|token|access[-_]?token|id[-_]?token|refresh[-_]?token|api[-_]?key|apikey|key|subscription[-_]?key|code|password|pwd|auth|jwt|hmac|policy|credential|se|sp|sv|st|srt|ss|skoid|sktid|sig)(?:$|[-_])/i;
-/**
- * Free-text credential shapes. Every pattern is a linear scan over bounded
- * character classes — no nested quantifiers, no backtracking traps (the repo's
- * CodeQL ReDoS rule).
- */
-const CREDENTIAL_PATTERNS = [
-    [/\b(?:Bearer|Basic|Digest|Negotiate)\s+[A-Za-z0-9._~+/=-]{8,}/gi, "[REDACTED_AUTH]"],
-    // `scheme://user:password@host` — basic-auth credentials embedded in a URL.
-    // `projectExportEndpoint` refuses these structurally, but a URL can also reach
-    // an export through an adapter's free-text error message, so the text scan has
-    // to recognize the same shape.
-    [/\b[a-z][a-z0-9+.-]{1,31}:\/\/[^\s/@:]{1,128}:[^\s/@]{1,128}@/gi, "[REDACTED_URL_CREDENTIALS]@"],
-    [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{4,}/g, "[REDACTED_JWT]"],
-    [/\bAKIA[0-9A-Z]{16}\b/g, "[REDACTED_AWS_KEY]"],
-    [/\bASIA[0-9A-Z]{16}\b/g, "[REDACTED_AWS_KEY]"],
-    [/\bAIza[0-9A-Za-z_-]{20,}/g, "[REDACTED_PROVIDER_TOKEN]"],
-    [/\bgh[pousr]_[A-Za-z0-9]{16,}/g, "[REDACTED_PROVIDER_TOKEN]"],
-    [/\bglpat-[A-Za-z0-9_-]{10,}/g, "[REDACTED_PROVIDER_TOKEN]"],
-    [/\bxox[baprs]-[A-Za-z0-9-]{8,}/gi, "[REDACTED_PROVIDER_TOKEN]"],
-    [/\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{8,}/gi, "[REDACTED_PROVIDER_TOKEN]"],
-    [/\bsk-[A-Za-z0-9]{16,}/g, "[REDACTED_PROVIDER_TOKEN]"],
-    // Labelled `name=value` / `name: value` pairs. The name alternation covers
-    // the short, provider-specific parameter names real signed URLs use — Azure
-    // SAS `sig`/`sv`/`se`/`st`, AWS/GCS `x-amz-signature`/`x-goog-signature`, and
-    // the bare `key` that tile providers favour — because those values are
-    // frequently *short* (a 24-character SAS signature is common) and so slip
-    // under any entropy heuristic. `\b` before each name keeps `turnkey=` and
-    // `monkey=` from matching.
-    [
-        /\b(access[-_]?key|api[-_]?key|apikey|authorization|client[-_]?secret|cookie|credential|jwt|key|pass(?:password)?|password|pwd|se|secret|session|sig|signature|st|subscription[-_]?key|sv|token|x-amz-[a-z-]{1,32}|x-goog-[a-z-]{1,32})\s*[:=]\s*(?:"[^"]{0,512}"|'[^']{0,512}'|[^\s&,;}"']{1,512})/gi,
-        `$1=${HONUA_EXPORT_REDACTED}`,
-    ],
-];
-/**
- * High-entropy blob heuristic, applied last so labelled matches win first.
- *
- * Deliberately excludes `/` and `-` from the character class. Including them
- * made ordinary URL paths match — `arcgis/rest/services/Roads/FeatureServer/0`
- * is 41 characters of `[A-Za-z0-9/]` and was being reported as a secret, which
- * would have thrown away the endpoint an attribution block legitimately needs.
- * Base64 blobs containing `/` still get caught: in practice they appear as a
- * labelled parameter value or an `Authorization` header, both of which the
- * patterns above match first.
- */
-const OPAQUE_SECRET = /\b[A-Za-z0-9_+=]{40,}\b/g;
-function decodePercentEncoding(value) {
-    let decoded = value;
-    for (let pass = 0; pass < 2; pass += 1) {
-        if (!decoded.includes("%"))
-            break;
-        let next;
-        try {
-            next = decodeURIComponent(decoded);
-        }
-        catch {
-            break;
-        }
-        if (next === decoded)
-            break;
-        decoded = next;
-    }
-    return decoded;
-}
-/**
- * Redacts credential material from arbitrary human-readable text: adapter
- * error messages, titles, status strings, log lines, event detail messages.
- *
- * Percent-encoded payloads are decoded (twice, bounded) before matching so a
- * `%42earer%20abc` style evasion cannot slip a token past the scan; the
- * returned string is the redacted *decoded* form when decoding changed
- * anything, because emitting the still-encoded original would defeat the
- * point.
- */
-export function redactHonuaExportText(value) {
-    if (value.length === 0)
-        return value;
-    let redacted = decodePercentEncoding(value);
-    for (const [pattern, replacement] of CREDENTIAL_PATTERNS) {
-        redacted = redacted.replace(pattern, replacement);
-    }
-    return redacted.replace(OPAQUE_SECRET, "[REDACTED_TOKEN]");
-}
-/** Whether `value` still looks like it carries credential material. */
-export function containsCredentialMaterial(value) {
-    return redactHonuaExportText(value) !== decodePercentEncoding(value);
-}
-/**
- * Fail-closed assertion for finished export payloads (REQ-002). Throws
- * {@link HonuaExportSafetyError} rather than scrubbing, because reaching this
- * point with credential material means an earlier layer is broken.
- */
-export function assertCredentialFreeExportText(value, label) {
-    if (containsCredentialMaterial(value)) {
-        throw new HonuaExportSafetyError(`${label} still contains credential material after redaction; refusing to emit the export.`, "assertion");
-    }
-}
-// ── binary artifact scanning ─────────────────────────────────────────────
-/** Shortest printable run worth scanning. Below this it is structural noise, not text. */
-const MIN_PRINTABLE_RUN = 4;
-/** Printable text accumulated before a chunk is scanned and flushed. */
-const PRINTABLE_CHUNK_BYTES = 1 << 20;
 /**
- * Characters carried between chunks so a token straddling a flush boundary is
- * still matched. Comfortably longer than the longest pattern this module has.
+ * The credential recognizer itself now lives in `src/core/credential-redaction.ts`
+ * so `src/runtime`'s portable MapPackage export (#1426) can share exactly one
+ * scanner across the `@honua/sdk` / `@honua/app-platform` split-package
+ * boundary. Every symbol is re-exported here unchanged: this module's published
+ * surface, and its two-layer guarantee, are identical to before the move.
  */
-const PRINTABLE_CHUNK_OVERLAP = 512;
-/**
- * Extracts runs of printable ASCII from a binary buffer, joined by newlines.
- *
- * This is the `strings(1)` idea, and it exists because "binary" is not a
- * security boundary. A PNG `tEXt`/`iTXt` chunk, a JPEG `COM` marker, PDF
- * metadata or an embedded XMP packet, an EXIF `UserComment`, a ZIP comment —
- * all carry plainly readable text inside a buffer that will never decode as
- * UTF-8 as a whole. Scanning only whole-buffer-decodable artifacts would let a
- * token ride out inside any of them.
- *
- * Runs shorter than {@link MIN_PRINTABLE_RUN} are dropped: they are the
- * incidental byte values that fall in the ASCII range inside compressed data,
- * and keeping them would produce noise without ever forming a credential.
- */
-export function extractPrintableRuns(bytes, start = 0, end = bytes.byteLength) {
-    const runs = [];
-    let current = "";
-    for (let index = start; index < end; index += 1) {
-        const byte = bytes[index];
-        // Printable ASCII plus tab. Deliberately not the full latin-1 upper range:
-        // every credential shape this module recognizes is ASCII, and admitting
-        // 0x80-0xFF would turn arbitrary compressed data into "text".
-        if ((byte >= 0x20 && byte <= 0x7e) || byte === 0x09) {
-            current += String.fromCharCode(byte);
-            continue;
-        }
-        if (current.length >= MIN_PRINTABLE_RUN)
-            runs.push(current);
-        current = "";
-    }
-    if (current.length >= MIN_PRINTABLE_RUN)
-        runs.push(current);
-    return runs.join("\n");
-}
-/**
- * Fail-closed credential scan over a binary artifact (REQ-002).
- *
- * Scans in bounded chunks with an overlap, so an arbitrarily large artifact
- * costs bounded memory while a token that straddles a chunk boundary is still
- * caught. Throws {@link HonuaExportSafetyError} on a hit, like the text scan —
- * a credential surviving to this point means an earlier layer is broken, and
- * emitting the bytes anyway is the one outcome that cannot be walked back.
- */
-export function assertCredentialFreeExportBytes(bytes, label) {
-    let carry = "";
-    for (let offset = 0; offset < bytes.byteLength; offset += PRINTABLE_CHUNK_BYTES) {
-        const end = Math.min(bytes.byteLength, offset + PRINTABLE_CHUNK_BYTES);
-        const printable = extractPrintableRuns(bytes, offset, end);
-        if (printable.length === 0 && carry.length === 0)
-            continue;
-        assertCredentialFreeExportText(`${carry}${printable}`, label);
-        carry = printable.slice(-PRINTABLE_CHUNK_OVERLAP);
-    }
-}
-/**
- * Reduces a source URL to `origin + pathname`, always dropping the query
- * string and fragment.
- *
- * Query strings are where every practical map-service credential lives (Esri
- * `?token=`, Azure SAS `?sv=...&sig=`, S3/GCS presigned `?X-Amz-Signature=`,
- * tile-provider `?api_key=`), and a partial per-parameter allowlist has to be
- * right about every provider forever. Dropping the whole query is the only
- * rule that is right by construction; the origin+path that remains is what an
- * attribution/provenance block legitimately needs.
- *
- * Non-HTTP(S) schemes (`data:`, `blob:`, `file:`), URLs with embedded
- * `user:password@` userinfo, and unparseable strings yield no endpoint at all.
- */
-export function projectExportEndpoint(url) {
-    const trimmed = url.trim();
-    if (trimmed.length === 0 || trimmed.length > 4096) {
-        return { endpoint: undefined, reason: "unsupported-value" };
-    }
-    let parsed;
-    try {
-        parsed = new URL(trimmed);
-    }
-    catch {
-        // Relative locators carry no host and therefore no credential context, but
-        // they can still carry a query string; keep only the path portion.
-        const [path] = trimmed.split(/[?#]/, 1);
-        if (path.length === 0 || containsCredentialMaterial(path)) {
-            return { endpoint: undefined, reason: "credential-pattern" };
-        }
-        return path === trimmed ? { endpoint: path } : { endpoint: path, reason: "signed-url" };
-    }
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-        return { endpoint: undefined, reason: "unsupported-value" };
-    }
-    if (parsed.username.length > 0 || parsed.password.length > 0) {
-        return { endpoint: undefined, reason: "signed-url" };
-    }
-    const hadSecretQuery = [...parsed.searchParams.keys()].some((name) => SIGNED_QUERY_NAME.test(name) || SENSITIVE_KEY.test(name));
-    const endpoint = `${parsed.origin}${parsed.pathname}`;
-    if (containsCredentialMaterial(endpoint)) {
-        return { endpoint: undefined, reason: "credential-pattern" };
-    }
-    const droppedSomething = parsed.search.length > 0 || parsed.hash.length > 0;
-    if (hadSecretQuery)
-        return { endpoint, reason: "signed-url" };
-    return droppedSomething ? { endpoint, reason: "unsupported-value" } : { endpoint };
-}
+export { HONUA_EXPORT_REDACTED, HonuaExportSafetyError, assertCredentialFreeExportBytes, assertCredentialFreeExportText, containsCredentialMaterial, extractPrintableRuns, isSensitiveExportKey, projectExportEndpoint, redactHonuaExportText, sanitizeHonuaExportHeaders, } from "../core/credential-redaction.js";
 // ── filenames ────────────────────────────────────────────────────────────
 const FILENAME_FALLBACK = "honua-export";
 const FILENAME_MAX_LENGTH = 96;
@@ -555,34 +333,3 @@ export function sanitizeHonuaExportState(state, options = {}) {
  * export (a server-side renderer, a tile fetch for a print layout). Everything
  * outside this set is a private header for export purposes (REQ-002).
  */
-const EXPORTABLE_HEADERS = new Set(["accept", "accept-language", "content-type", "user-agent"]);
-/**
- * Filters a header map down to the export allowlist, recording every drop.
- * Exposed so adapters can prove — in their own tests — that no `Authorization`,
- * `Cookie`, or provider-specific key header rides along with export metadata.
- */
-export function sanitizeHonuaExportHeaders(headers) {
-    const redactions = [];
-    const output = {};
-    for (const [rawName, rawValue] of Object.entries(headers ?? {})) {
-        const name = rawName.toLowerCase();
-        if (!EXPORTABLE_HEADERS.has(name)) {
-            redactions.push({
-                path: `headers[${name}]`,
-                reason: SENSITIVE_KEY.test(name) || AUTHORIZATION_SCOPE_KEY.test(name) ? "sensitive-key" : "private-header",
-            });
-            continue;
-        }
-        const value = redactHonuaExportText(rawValue);
-        if (value !== rawValue) {
-            redactions.push({ path: `headers[${name}]`, reason: "credential-pattern" });
-            continue;
-        }
-        output[name] = value.slice(0, 512);
-    }
-    return { headers: output, redactions };
-}
-/** Whether a property name is refused outright by the export pipeline. */
-export function isSensitiveExportKey(name) {
-    return SENSITIVE_KEY.test(name) || AUTHORIZATION_SCOPE_KEY.test(name);
-}

package/web-components/feature-editor-offline.d.ts

@@ -0,0 +1,32 @@
+import type { OfflineEditEnqueueResult, OfflineEditQueue, OfflineEditQueuePartition, OfflineQueuedEdit } from "../offline/edit-queue.js";
+import type { HonuaFeatureEditorConflictChoice, HonuaFeatureEditorOfflineState, HonuaFeatureEditorSnapshot, HonuaFeatureEditorWorkflow } from "./feature-editor-workflow.js";
+export type HonuaFeatureEditorOfflineErrorCode = "invalid-draft" | "attachment-payload" | "invalid-value";
+/** A draft cannot be persisted without an explicit, lossless queue mapping. */
+export declare class HonuaFeatureEditorOfflineError extends Error {
+    readonly code: HonuaFeatureEditorOfflineErrorCode;
+    readonly name = "HonuaFeatureEditorOfflineError";
+    constructor(code: HonuaFeatureEditorOfflineErrorCode, message: string);
+}
+export interface QueueHonuaFeatureEditorDraftOptions {
+    /** Precomputed authorization partition digest. Raw credentials are never accepted. */
+    readonly authorizationScopeDigest: `sha256:${string}`;
+    readonly idempotencyKey: string;
+    readonly dependencyIds?: readonly `sha256:${string}`[];
+}
+export interface QueueHonuaFeatureEditorDraftResult<T = Record<string, unknown>> {
+    readonly enqueue: OfflineEditEnqueueResult;
+    readonly snapshot: HonuaFeatureEditorSnapshot<T>;
+}
+/**
+ * Persist the current validated draft in the canonical offline edit queue.
+ * Attachment payloads fail closed because the queue contract cannot represent
+ * them; silently dropping a staged upload would make the recovered edit lie.
+ */
+export declare function queueHonuaFeatureEditorDraft<T>(workflow: HonuaFeatureEditorWorkflow<T>, queue: OfflineEditQueue, options: QueueHonuaFeatureEditorDraftOptions): Promise<QueueHonuaFeatureEditorDraftResult<T>>;
+/** Project a later replay/reconnect transition back into the same workflow. */
+export declare function reconcileHonuaFeatureEditorOfflineEdit<T>(workflow: HonuaFeatureEditorWorkflow<T>, edit: OfflineQueuedEdit): HonuaFeatureEditorSnapshot<T>;
+/** Resolve a queued conflict durably before updating the component state. */
+export declare function resolveHonuaFeatureEditorOfflineConflict<T>(workflow: HonuaFeatureEditorWorkflow<T>, queue: OfflineEditQueue, edit: OfflineQueuedEdit, choice: HonuaFeatureEditorConflictChoice, partition: OfflineEditQueuePartition): Promise<HonuaFeatureEditorSnapshot<T>>;
+/** Convert the durable queue record to the payload-free component projection. */
+export declare function offlineStateFromQueuedEdit(edit: OfflineQueuedEdit): HonuaFeatureEditorOfflineState;
+//# sourceMappingURL=feature-editor-offline.d.ts.map

package/web-components/feature-editor-offline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-editor-offline.d.ts","sourceRoot":"","sources":["../../../src/web-components/feature-editor-offline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EAExB,gBAAgB,EAChB,yBAAyB,EACzB,iBAAiB,EAClB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EACV,gCAAgC,EAChC,8BAA8B,EAC9B,0BAA0B,EAC1B,0BAA0B,EAC3B,MAAM,8BAA8B,CAAC;AAEtC,MAAM,MAAM,kCAAkC,GAAG,eAAe,GAAG,oBAAoB,GAAG,eAAe,CAAC;AAE1G,+EAA+E;AAC/E,qBAAa,8BAA+B,SAAQ,KAAK;aAIrC,IAAI,EAAE,kCAAkC;IAH1D,SAAgB,IAAI,oCAAoC;gBAGtC,IAAI,EAAE,kCAAkC,EACxD,OAAO,EAAE,MAAM;CAIlB;AAED,MAAM,WAAW,mCAAmC;IAClD,sFAAsF;IACtF,QAAQ,CAAC,wBAAwB,EAAE,UAAU,MAAM,EAAE,CAAC;IACtD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,UAAU,MAAM,EAAE,EAAE,CAAC;CACxD;AAED,MAAM,WAAW,kCAAkC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC7E,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,CAAC,CAAC,CAAC,CAAC;CAClD;AAED;;;;GAIG;AACH,wBAAsB,4BAA4B,CAAC,CAAC,EAClD,QAAQ,EAAE,0BAA0B,CAAC,CAAC,CAAC,EACvC,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,mCAAmC,GAC3C,OAAO,CAAC,kCAAkC,CAAC,CAAC,CAAC,CAAC,CAyChD;AAED,+EAA+E;AAC/E,wBAAgB,sCAAsC,CAAC,CAAC,EACtD,QAAQ,EAAE,0BAA0B,CAAC,CAAC,CAAC,EACvC,IAAI,EAAE,iBAAiB,GACtB,0BAA0B,CAAC,CAAC,CAAC,CAE/B;AAED,6EAA6E;AAC7E,wBAAsB,wCAAwC,CAAC,CAAC,EAC9D,QAAQ,EAAE,0BAA0B,CAAC,CAAC,CAAC,EACvC,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,gCAAgC,EACxC,SAAS,EAAE,yBAAyB,GACnC,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAUxC;AAED,iFAAiF;AACjF,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,iBAAiB,GAAG,8BAA8B,CAmBlG"}

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

@@ -0,0 +1,115 @@
+/** A draft cannot be persisted without an explicit, lossless queue mapping. */
+export class HonuaFeatureEditorOfflineError extends Error {
+    code;
+    name = "HonuaFeatureEditorOfflineError";
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/**
+ * Persist the current validated draft in the canonical offline edit queue.
+ * Attachment payloads fail closed because the queue contract cannot represent
+ * them; silently dropping a staged upload would make the recovered edit lie.
+ */
+export async function queueHonuaFeatureEditorDraft(workflow, queue, options) {
+    const snapshot = workflow.snapshot();
+    const model = workflow.sketchModel();
+    if (!model || !snapshot.operation || !snapshot.form) {
+        throw new HonuaFeatureEditorOfflineError("invalid-draft", "Open an edit draft before adding it to the offline queue.");
+    }
+    if (!workflow.validate().valid) {
+        throw new HonuaFeatureEditorOfflineError("invalid-draft", "Fix validation errors before adding the edit to the offline queue.");
+    }
+    if (snapshot.attachments.length > 0) {
+        throw new HonuaFeatureEditorOfflineError("attachment-payload", "Offline feature edits do not persist attachment payloads. Remove the staged attachments or submit while online.");
+    }
+    const feature = model.snapshot().feature;
+    const attributes = jsonRecord(feature.attributes, "attributes");
+    const geometry = feature.geometry === undefined ? undefined : jsonValue(feature.geometry, "geometry");
+    const enqueue = await queue.enqueue({
+        authorizationScopeDigest: options.authorizationScopeDigest,
+        sourceId: workflow.source.descriptor.id,
+        idempotencyKey: requiredText(options.idempotencyKey, "idempotencyKey"),
+        edit: {
+            operation: snapshot.operation === "create" ? "add" : snapshot.operation,
+            ...(feature.id !== undefined ? { featureId: feature.id } : {}),
+            ...(Object.keys(attributes).length > 0 ? { attributes } : {}),
+            ...(geometry !== undefined ? { geometry } : {}),
+        },
+        ...(options.dependencyIds ? { dependencyIds: options.dependencyIds } : {}),
+    });
+    return Object.freeze({
+        enqueue,
+        snapshot: workflow.applyOfflineState(offlineStateFromQueuedEdit(enqueue.edit)),
+    });
+}
+/** Project a later replay/reconnect transition back into the same workflow. */
+export function reconcileHonuaFeatureEditorOfflineEdit(workflow, edit) {
+    return workflow.applyOfflineState(offlineStateFromQueuedEdit(edit));
+}
+/** Resolve a queued conflict durably before updating the component state. */
+export async function resolveHonuaFeatureEditorOfflineConflict(workflow, queue, edit, choice, partition) {
+    const conflictId = edit.conflict?.conflictId;
+    if (edit.state !== "conflicted" || !conflictId) {
+        throw new HonuaFeatureEditorOfflineError("invalid-draft", "The offline edit does not have a conflict to resolve.");
+    }
+    const resolved = await queue.resolveConflict(edit.id, partition, {
+        conflictId,
+        choice: choice === "keep-mine" ? "accept-client" : "accept-server",
+    });
+    return reconcileHonuaFeatureEditorOfflineEdit(workflow, resolved);
+}
+/** Convert the durable queue record to the payload-free component projection. */
+export function offlineStateFromQueuedEdit(edit) {
+    const state = edit.state === "leased"
+        ? "pending"
+        : edit.state === "cancelled" && edit.conflictResolution?.disposition === "discarded"
+            ? "discarded"
+            : edit.state;
+    return Object.freeze({
+        sourceId: edit.sourceId,
+        queueId: edit.id,
+        idempotencyKey: edit.idempotencyKey,
+        state,
+        ...(edit.retry?.retryAt ? { retryAt: edit.retry.retryAt } : {}),
+        ...(edit.retry?.reasonCode ? { reasonCode: edit.retry.reasonCode } : {}),
+        ...(edit.applied?.appliedAt ? { appliedAt: edit.applied.appliedAt } : {}),
+        ...(edit.conflict?.conflictId ? { conflictId: edit.conflict.conflictId } : {}),
+        ...(edit.conflict?.serverGeneration ? { serverGeneration: edit.conflict.serverGeneration } : {}),
+        ...(edit.cancellation?.reasonCode ? { reasonCode: edit.cancellation.reasonCode } : {}),
+    });
+}
+function jsonRecord(value, path) {
+    if (!isRecord(value))
+        throw invalidValue(path);
+    const output = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (item !== undefined)
+            output[key] = jsonValue(item, `${path}.${key}`);
+    }
+    return output;
+}
+function jsonValue(value, path) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (Array.isArray(value))
+        return value.map((item, index) => jsonValue(item, `${path}[${index}]`));
+    if (isRecord(value))
+        return jsonRecord(value, path);
+    throw invalidValue(path);
+}
+function invalidValue(path) {
+    return new HonuaFeatureEditorOfflineError("invalid-value", `${path} must contain only JSON-compatible values.`);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requiredText(value, name) {
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        throw new HonuaFeatureEditorOfflineError("invalid-draft", `${name} is required.`);
+    return normalized;
+}