@honua/app-platform 0.0.20-alpha.0

package/replica-sync/fixture.js

@@ -0,0 +1,364 @@
+/**
+ * In-memory fixture transport for disconnected replica and sync-conflict
+ * review. It powers Console and Studio temporal/conflict viewer prototypes and
+ * SDK tests without a live server.
+ *
+ * The default seed covers the states the issue calls out: an active replica, an
+ * expired replica, a pending conflict, an already-resolved conflict, a batch of
+ * conflicts, and a dataset where conflict review is unsupported.
+ *
+ * @module
+ */
+import { HonuaReplicaSyncError } from "./errors.js";
+const FULL_CAPABILITIES = {
+    sync: true,
+    createReplica: true,
+    synchronizeReplica: true,
+    conflictReview: true,
+    conflictResolution: true,
+    conflictPolicies: ["server-wins", "client-wins", "manual"],
+    directions: ["bidirectional", "upload", "download"],
+};
+const NO_CONFLICT_REVIEW_CAPABILITIES = {
+    sync: true,
+    createReplica: true,
+    synchronizeReplica: true,
+    conflictReview: false,
+    conflictResolution: false,
+    conflictPolicies: ["server-wins", "client-wins"],
+    directions: ["bidirectional"],
+};
+export function createFixtureReplicaSyncTransport(options = {}) {
+    return new FixtureReplicaSyncTransport(options);
+}
+export class FixtureReplicaSyncTransport {
+    #now;
+    #capabilities = new Map();
+    #replicas = new Map();
+    #conflicts = new Map();
+    constructor(options = {}) {
+        this.#now = options.now ?? (() => new Date());
+        const seed = options.seed ?? defaultSeed();
+        for (const [key, value] of Object.entries(seed.capabilities ?? {}))
+            this.#capabilities.set(key, value);
+        for (const replica of seed.replicas ?? [])
+            this.#replicas.set(replica.id, replica);
+        for (const conflict of seed.conflicts ?? [])
+            this.#conflicts.set(conflict.id, conflict);
+    }
+    async capabilities(datasetId, sourceId) {
+        const key = capabilityKey(datasetId, sourceId);
+        const caps = this.#capabilities.get(key) ?? this.#capabilities.get(datasetId);
+        if (!caps) {
+            throw new HonuaReplicaSyncError("unsupported-sync", `Disconnected sync is not available for dataset "${datasetId}".`);
+        }
+        return caps;
+    }
+    async listReplicas(request = {}) {
+        const items = [...this.#replicas.values()].filter((replica) => {
+            if (request.datasetId !== undefined && replica.datasetId !== request.datasetId)
+                return false;
+            if (request.sourceId !== undefined && replica.sourceId !== request.sourceId)
+                return false;
+            if (request.ownerId !== undefined && replica.owner?.id !== request.ownerId)
+                return false;
+            if (request.states !== undefined && !request.states.includes(replica.state))
+                return false;
+            return true;
+        });
+        return paginate(items, request.limit, request.cursor);
+    }
+    async getReplica(replicaId) {
+        const replica = this.#replicas.get(replicaId);
+        if (!replica) {
+            throw new HonuaReplicaSyncError("replica-not-found", `Replica "${replicaId}" was not found.`);
+        }
+        return replica;
+    }
+    async listConflicts(request = {}) {
+        const replica = request.replicaId === undefined ? undefined : this.#replicas.get(request.replicaId);
+        if (request.replicaId !== undefined && replica === undefined) {
+            throw new HonuaReplicaSyncError("replica-not-found", `Replica "${request.replicaId}" was not found.`);
+        }
+        this.assertConflictReviewSupported(replica?.datasetId ?? request.datasetId);
+        const items = [...this.#conflicts.values()].filter((conflict) => {
+            if (request.replicaId !== undefined && conflict.replicaId !== request.replicaId)
+                return false;
+            if (request.datasetId !== undefined && conflict.datasetId !== request.datasetId)
+                return false;
+            if (request.statuses !== undefined && !request.statuses.includes(conflict.status))
+                return false;
+            if (request.kinds !== undefined && !request.kinds.includes(conflict.kind))
+                return false;
+            return true;
+        });
+        return paginate(items.map(toSummary), request.limit, request.cursor);
+    }
+    async getConflict(conflictId) {
+        const conflict = this.#conflicts.get(conflictId);
+        if (!conflict) {
+            throw new HonuaReplicaSyncError("conflict-not-found", `Sync conflict "${conflictId}" was not found.`);
+        }
+        this.assertConflictReviewSupported(conflict.datasetId);
+        return conflict;
+    }
+    async resolveConflict(resolution) {
+        const conflict = this.#conflicts.get(resolution.conflictId);
+        if (!conflict) {
+            throw new HonuaReplicaSyncError("conflict-not-found", `Sync conflict "${resolution.conflictId}" was not found.`);
+        }
+        this.assertConflictReviewSupported(conflict.datasetId);
+        if (conflict.status === "resolved" || conflict.status === "discarded") {
+            throw new HonuaReplicaSyncError("conflict-already-resolved", `Sync conflict "${conflict.id}" is already resolved.`, {
+                details: { status: conflict.status },
+            });
+        }
+        const record = {
+            conflictId: conflict.id,
+            choice: resolution.choice,
+            status: resolution.choice === "discard" ? "discarded" : "resolved",
+            resolvedAt: this.#now().toISOString(),
+            resolvedBy: resolution.resolvedBy,
+            serverGen: bumpServerGen(conflict.serverGen),
+            note: resolution.note,
+        };
+        this.#conflicts.set(conflict.id, { ...conflict, status: record.status, resolution: record });
+        return record;
+    }
+    async resolveConflicts(resolutions) {
+        const records = [];
+        const failures = [];
+        for (const resolution of resolutions) {
+            try {
+                records.push(await this.resolveConflict(resolution));
+            }
+            catch (error) {
+                failures.push({
+                    conflictId: resolution.conflictId,
+                    reason: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        return { records, failures };
+    }
+    assertConflictReviewSupported(datasetId) {
+        if (datasetId === undefined)
+            return;
+        const caps = this.#capabilities.get(datasetId);
+        if (caps && !caps.conflictReview) {
+            throw new HonuaReplicaSyncError("unsupported-conflict-review", `Manual conflict review is not available for dataset "${datasetId}".`);
+        }
+    }
+}
+function capabilityKey(datasetId, sourceId) {
+    return sourceId === undefined ? datasetId : `${datasetId}::${sourceId}`;
+}
+function toSummary(conflict) {
+    const { base: _base, clientState: _clientState, serverState: _serverState, fieldConflicts: _fieldConflicts, geometryConflict: _geometryConflict, resolutionOptions: _resolutionOptions, resolution: _resolution, serverGen: _serverGen, metadata: _metadata, ...summary } = conflict;
+    return summary;
+}
+function paginate(items, limit, cursor) {
+    const start = cursor === undefined ? 0 : Math.max(0, Number.parseInt(cursor, 10) || 0);
+    const end = limit === undefined ? items.length : start + limit;
+    const page = items.slice(start, end);
+    const nextCursor = end < items.length ? String(end) : undefined;
+    return { items: page, cursor: nextCursor, totalCount: items.length };
+}
+function bumpServerGen(serverGen) {
+    const current = serverGen === undefined ? 0 : Number.parseInt(serverGen, 10) || 0;
+    return String(current + 1);
+}
+/**
+ * Default seed covering every state the issue enumerates. Re-export so apps and
+ * tests can extend it.
+ */
+export function defaultSeed() {
+    const owner = { id: "user-amelia", displayName: "Amelia Stone", kind: "user" };
+    const device = { id: "device-field-01", displayName: "Field Tablet 01", platform: "android" };
+    const activeReplica = {
+        id: "replica-active-1",
+        name: "Parcels — North District",
+        datasetId: "parcels",
+        sourceId: "parcels",
+        state: "active",
+        direction: "bidirectional",
+        conflictPolicy: "manual",
+        owner,
+        device,
+        createdAt: "2026-05-20T08:00:00.000Z",
+        expiresAt: "2026-06-20T08:00:00.000Z",
+        status: {
+            serverGen: "42",
+            targetServerGen: "47",
+            lastSyncedAt: "2026-05-28T16:30:00.000Z",
+            lastSyncDirection: "bidirectional",
+            inProgress: false,
+            pendingUploads: 3,
+            pendingDownloads: 5,
+            openConflicts: 2,
+        },
+    };
+    const expiredReplica = {
+        id: "replica-expired-1",
+        name: "Inspections — South District",
+        datasetId: "inspections",
+        sourceId: "inspections",
+        state: "expired",
+        direction: "upload",
+        conflictPolicy: "server-wins",
+        owner: { id: "user-noah", displayName: "Noah Patel", kind: "user" },
+        device: { id: "device-field-07", displayName: "Field Tablet 07", platform: "ios" },
+        createdAt: "2026-03-01T08:00:00.000Z",
+        expiresAt: "2026-04-01T08:00:00.000Z",
+        status: {
+            serverGen: "11",
+            lastSyncedAt: "2026-03-30T12:00:00.000Z",
+            lastSyncDirection: "upload",
+            inProgress: false,
+            pendingUploads: 0,
+            pendingDownloads: 0,
+            openConflicts: 0,
+            lastError: "Replica lease expired before final synchronization.",
+        },
+    };
+    const pendingConflict = {
+        id: "conflict-pending-1",
+        replicaId: "replica-active-1",
+        datasetId: "parcels",
+        sourceId: "parcels",
+        layerId: 0,
+        featureId: "parcel-1024",
+        kind: "replica-sync",
+        status: "pending",
+        clientOperation: "update",
+        serverOperation: "update",
+        detectedAt: "2026-05-28T16:30:05.000Z",
+        fieldConflictCount: 1,
+        hasGeometryConflict: true,
+        client: owner,
+        device,
+        serverGen: "47",
+        base: {
+            operation: "update",
+            attributes: { zoning: "R1", area: 1200 },
+            editedAt: "2026-05-20T08:00:00.000Z",
+        },
+        clientState: {
+            operation: "update",
+            attributes: { zoning: "R2", area: 1200 },
+            geometry: { type: "Polygon", coordinates: [] },
+            editedAt: "2026-05-27T10:15:00.000Z",
+            editedBy: owner,
+            device,
+        },
+        serverState: {
+            operation: "update",
+            attributes: { zoning: "C1", area: 1200 },
+            geometry: { type: "Polygon", coordinates: [] },
+            editedAt: "2026-05-28T09:45:00.000Z",
+            editedBy: { id: "user-office", displayName: "Office Editor", kind: "user" },
+        },
+        fieldConflicts: [{ field: "zoning", baseValue: "R1", clientValue: "R2", serverValue: "C1", diverged: true }],
+        geometryConflict: {
+            changed: true,
+            clientChanged: true,
+            serverChanged: true,
+            geometryType: "Polygon",
+            divergenceMeters: 3.4,
+            note: "Both sides moved a shared vertex.",
+        },
+        resolutionOptions: [
+            { choice: "accept-client", label: "Keep field edit", available: true },
+            { choice: "accept-server", label: "Keep office edit", available: true },
+            { choice: "merge", label: "Merge values", available: true },
+            { choice: "discard", label: "Discard both", available: true },
+        ],
+    };
+    const resolvedConflict = {
+        id: "conflict-resolved-1",
+        replicaId: "replica-active-1",
+        datasetId: "parcels",
+        sourceId: "parcels",
+        layerId: 0,
+        featureId: "parcel-2048",
+        kind: "replica-sync",
+        status: "resolved",
+        clientOperation: "update",
+        serverOperation: "delete",
+        detectedAt: "2026-05-26T11:00:00.000Z",
+        fieldConflictCount: 0,
+        hasGeometryConflict: false,
+        client: owner,
+        device,
+        serverGen: "44",
+        base: { operation: "update", attributes: { owner: "Acme" } },
+        clientState: {
+            operation: "update",
+            attributes: { owner: "Acme Holdings" },
+            editedAt: "2026-05-25T14:00:00.000Z",
+            editedBy: owner,
+            device,
+        },
+        serverState: {
+            operation: "delete",
+            deleted: true,
+            editedAt: "2026-05-26T10:00:00.000Z",
+            editedBy: { id: "user-office", displayName: "Office Editor", kind: "user" },
+        },
+        fieldConflicts: [],
+        resolutionOptions: [
+            { choice: "accept-client", label: "Restore feature", available: true },
+            { choice: "accept-server", label: "Keep deletion", available: true },
+            { choice: "merge", label: "Merge values", available: false, reason: "Server side was deleted." },
+            { choice: "discard", label: "Discard", available: true },
+        ],
+        resolution: {
+            conflictId: "conflict-resolved-1",
+            choice: "accept-client",
+            status: "resolved",
+            resolvedAt: "2026-05-26T12:00:00.000Z",
+            resolvedBy: owner,
+            serverGen: "45",
+            note: "Restored — feature was edited in the field after the office delete.",
+        },
+    };
+    // A second pending conflict so batch-resolution scenarios have >1 input.
+    const batchConflict = {
+        ...pendingConflict,
+        id: "conflict-pending-2",
+        featureId: "parcel-3072",
+        detectedAt: "2026-05-28T16:31:00.000Z",
+        serverGen: "47",
+        fieldConflicts: [{ field: "area", baseValue: 1200, clientValue: 1250, serverValue: 1300, diverged: true }],
+        fieldConflictCount: 1,
+        hasGeometryConflict: false,
+        geometryConflict: undefined,
+    };
+    // Dataset that supports sync but not manual conflict review.
+    const unsupportedReviewReplica = {
+        id: "replica-no-review-1",
+        name: "Hydrants — server-wins",
+        datasetId: "hydrants",
+        sourceId: "hydrants",
+        state: "active",
+        direction: "bidirectional",
+        conflictPolicy: "server-wins",
+        createdAt: "2026-05-22T08:00:00.000Z",
+        status: {
+            serverGen: "9",
+            lastSyncedAt: "2026-05-29T07:00:00.000Z",
+            lastSyncDirection: "bidirectional",
+            inProgress: false,
+            openConflicts: 0,
+        },
+    };
+    return {
+        capabilities: {
+            parcels: FULL_CAPABILITIES,
+            inspections: FULL_CAPABILITIES,
+            hydrants: NO_CONFLICT_REVIEW_CAPABILITIES,
+        },
+        replicas: [activeReplica, expiredReplica, unsupportedReviewReplica],
+        conflicts: [pendingConflict, resolvedConflict, batchConflict],
+    };
+}

package/replica-sync/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Disconnected replica and sync-conflict SDK contracts.
+ *
+ * Console, MCP, QGIS, Studio, and mobile-adjacent tools share one product
+ * contract for disconnected replica metadata and sync conflict review. The
+ * surface is Esri-aligned (Sync, createReplica, synchronizeReplica, replica
+ * names, server generation cursors, conflict behavior) without hard-coding
+ * ArcGIS-only names, and composes with the temporal history contracts in
+ * honua-sdk-js#227.
+ *
+ * @experimental This entrypoint is not yet covered by the SDK's semver
+ *   contract — the surface may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+export { HonuaReplicaSyncClient, createHonuaReplicaSync } from "./client.js";
+export type { HonuaReplicaSyncClientOptions } from "./client.js";
+export { HonuaReplicaSyncError, isHonuaReplicaSyncError, isUnsupportedReplicaSyncError, } from "./errors.js";
+export type { ReplicaSyncErrorCode } from "./errors.js";
+export { FixtureReplicaSyncTransport, createFixtureReplicaSyncTransport, defaultSeed as defaultReplicaSyncSeed, } from "./fixture.js";
+export type { FixtureReplicaSyncSeed, FixtureReplicaSyncTransportOptions, } from "./fixture.js";
+export type { BatchConflictResolutionResult, ConflictFeatureState, FeatureId, SourceId, ConflictResolutionChoice, ConflictResolutionOption, DisconnectedReplica, FieldConflict, GeometryConflictSummary, ListConflictsRequest, ListReplicasRequest, ReplicaConflictPolicy, ReplicaId, ReplicaState, ReplicaSyncCapabilities, ReplicaSyncDirection, ReplicaSyncStatus, ReplicaSyncTransport, ServerGenerationCursor, SyncActor, SyncConflictDetail, SyncConflictId, SyncConflictKind, SyncConflictOperation, SyncConflictResolution, SyncConflictResolutionRecord, SyncConflictStatus, SyncConflictSummary, SyncDevice, SyncPage, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/replica-sync/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/replica-sync/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,WAAW,IAAI,sBAAsB,GACtC,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,sBAAsB,EACtB,kCAAkC,GACnC,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,6BAA6B,EAC7B,oBAAoB,EACpB,SAAS,EACT,QAAQ,EACR,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,aAAa,EACb,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,SAAS,EACT,YAAY,EACZ,uBAAuB,EACvB,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACtB,SAAS,EACT,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,4BAA4B,EAC5B,kBAAkB,EAClB,mBAAmB,EACnB,UAAU,EACV,QAAQ,GACT,MAAM,YAAY,CAAC"}

package/replica-sync/index.js

@@ -0,0 +1,17 @@
+/**
+ * Disconnected replica and sync-conflict SDK contracts.
+ *
+ * Console, MCP, QGIS, Studio, and mobile-adjacent tools share one product
+ * contract for disconnected replica metadata and sync conflict review. The
+ * surface is Esri-aligned (Sync, createReplica, synchronizeReplica, replica
+ * names, server generation cursors, conflict behavior) without hard-coding
+ * ArcGIS-only names, and composes with the temporal history contracts in
+ * honua-sdk-js#227.
+ *
+ * @experimental This entrypoint is not yet covered by the SDK's semver
+ *   contract — the surface may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+export { HonuaReplicaSyncClient, createHonuaReplicaSync } from "./client.js";
+export { HonuaReplicaSyncError, isHonuaReplicaSyncError, isUnsupportedReplicaSyncError, } from "./errors.js";
+export { FixtureReplicaSyncTransport, createFixtureReplicaSyncTransport, defaultSeed as defaultReplicaSyncSeed, } from "./fixture.js";

package/replica-sync/types.d.ts

@@ -0,0 +1,270 @@
+/**
+ * Disconnected replica and sync-conflict SDK contracts.
+ *
+ * These types give Console, MCP, QGIS, Studio, and mobile-adjacent tools a
+ * single product-level shape for disconnected replica metadata and sync
+ * conflict review, instead of forcing every client to infer it from low-level
+ * sync responses. The model is Esri-aligned (replicas, server generation
+ * cursors, conflict behavior) but does not hard-code ArcGIS-only names into the
+ * public Honua surface.
+ *
+ * @module
+ */
+import type { FeatureId, SourceId } from "../contract/types.js";
+/**
+ * Re-exported so replica-sync conflict records compose directly with the
+ * temporal history contracts (honua-sdk-js#227), which key revisions and
+ * timelines by the same {@link FeatureId} / {@link SourceId} aliases. A reviewer
+ * can take a conflict's `featureId` and feed it straight into the temporal
+ * feature-timeline contract without re-typing.
+ */
+export type { FeatureId, SourceId } from "../contract/types.js";
+/** Stable identifier for a disconnected replica. */
+export type ReplicaId = string;
+/** Stable identifier for a sync conflict awaiting review. */
+export type SyncConflictId = string;
+/**
+ * Monotonic server generation cursor. A replica tracks the server generation it
+ * last synchronized against; the server advances this on every committed edit.
+ * Esri exposes this as `serverGen` on Sync responses — Honua keeps the cursor
+ * opaque so transports can use sequence numbers, hybrid logical clocks, or
+ * vector cursors.
+ */
+export type ServerGenerationCursor = string;
+/** Lifecycle state of a disconnected replica. */
+export type ReplicaState = "provisioning" | "active" | "syncing" | "out-of-date" | "expired" | "removed";
+/**
+ * How a replica reconciles concurrent edits when synchronizing. Mirrors Esri
+ * `createReplica` conflict behavior without binding to its wire spelling.
+ */
+export type ReplicaConflictPolicy = "server-wins" | "client-wins" | "manual" | "last-writer-wins";
+/** Direction(s) of data flow a replica supports. */
+export type ReplicaSyncDirection = "bidirectional" | "upload" | "download";
+/** Per-source capability flags advertised for a replica's parent dataset. */
+export interface ReplicaSyncCapabilities {
+    /** Replica creation / disconnected editing is offered at all. */
+    readonly sync: boolean;
+    /** Server can register new replicas (`createReplica`). */
+    readonly createReplica: boolean;
+    /** Existing replicas can be synchronized (`synchronizeReplica`). */
+    readonly synchronizeReplica: boolean;
+    /** Server retains per-conflict detail for manual review. */
+    readonly conflictReview: boolean;
+    /** Conflict resolutions can be submitted back through the SDK. */
+    readonly conflictResolution: boolean;
+    /** Supported reconciliation policies for new replicas. */
+    readonly conflictPolicies: ReadonlyArray<ReplicaConflictPolicy>;
+    /** Supported sync directions. */
+    readonly directions: ReadonlyArray<ReplicaSyncDirection>;
+}
+/** Actor (person, service, or agent) attributed to a replica or edit. */
+export interface SyncActor {
+    readonly id: string;
+    readonly displayName?: string;
+    readonly kind?: "user" | "service" | "agent" | (string & {});
+}
+/** Device a disconnected replica is checked out to. */
+export interface SyncDevice {
+    readonly id: string;
+    readonly displayName?: string;
+    readonly platform?: string;
+    readonly lastSeenAt?: string;
+}
+/** Outcome of the most recent synchronization attempt for a replica. */
+export interface ReplicaSyncStatus {
+    /** Server generation the replica was last reconciled against. */
+    readonly serverGen?: ServerGenerationCursor;
+    /** Server generation the replica is currently aware of (may be ahead). */
+    readonly targetServerGen?: ServerGenerationCursor;
+    readonly lastSyncedAt?: string;
+    readonly lastSyncDirection?: ReplicaSyncDirection;
+    readonly inProgress: boolean;
+    /** Count of edits uploaded but not yet acknowledged by the server. */
+    readonly pendingUploads?: number;
+    /** Count of server edits not yet applied to the replica. */
+    readonly pendingDownloads?: number;
+    /** Open conflicts attributed to this replica. */
+    readonly openConflicts: number;
+    readonly lastError?: string;
+}
+/** A disconnected replica registered against a Honua dataset. */
+export interface DisconnectedReplica {
+    readonly id: ReplicaId;
+    /**
+     * Human-facing replica name. Esri parity surfaces a server-assigned replica
+     * name; Honua keeps it optional and informational.
+     */
+    readonly name?: string;
+    readonly datasetId: string;
+    readonly sourceId?: SourceId;
+    readonly state: ReplicaState;
+    readonly direction: ReplicaSyncDirection;
+    readonly conflictPolicy: ReplicaConflictPolicy;
+    readonly owner?: SyncActor;
+    readonly device?: SyncDevice;
+    readonly createdAt: string;
+    /** When the replica's server-side lease expires; absent means no expiry. */
+    readonly expiresAt?: string;
+    readonly status: ReplicaSyncStatus;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Lifecycle of a single sync conflict. */
+export type SyncConflictStatus = "pending" | "resolving" | "resolved" | "discarded";
+/** The kind of edit that produced a conflicting side. */
+export type SyncConflictOperation = "create" | "update" | "delete";
+/**
+ * Distinguishes a disconnected-replica sync conflict from a named-version
+ * reconcile/post conflict. Clients use this to route review UI correctly and to
+ * avoid mixing the two conflict models (see honua-server#371).
+ */
+export type SyncConflictKind = "replica-sync" | "version-reconcile";
+/** A single conflicting attribute value. */
+export interface FieldConflict {
+    readonly field: string;
+    readonly baseValue?: unknown;
+    readonly clientValue?: unknown;
+    readonly serverValue?: unknown;
+    /** True when client and server diverged from the common base. */
+    readonly diverged: boolean;
+}
+/** Summary of a geometry-level conflict without shipping full geometries. */
+export interface GeometryConflictSummary {
+    readonly changed: boolean;
+    readonly clientChanged: boolean;
+    readonly serverChanged: boolean;
+    readonly geometryType?: string;
+    /** Hausdorff-style or area-delta hint, when the transport computes one. */
+    readonly divergenceMeters?: number;
+    readonly note?: string;
+}
+/** One side of a three-way conflict (base / client / server feature state). */
+export interface ConflictFeatureState {
+    readonly operation: SyncConflictOperation;
+    readonly attributes?: Readonly<Record<string, unknown>>;
+    readonly geometry?: unknown;
+    readonly editedAt?: string;
+    readonly editedBy?: SyncActor;
+    readonly device?: SyncDevice;
+    /** Present when the feature was deleted on this side. */
+    readonly deleted?: boolean;
+}
+/** How a single conflict may be resolved. */
+export type ConflictResolutionChoice = "accept-client" | "accept-server" | "merge" | "discard";
+/** A resolution option the server is willing to accept for a conflict. */
+export interface ConflictResolutionOption {
+    readonly choice: ConflictResolutionChoice;
+    readonly label?: string;
+    /** False when the option is shown but not currently selectable. */
+    readonly available: boolean;
+    readonly reason?: string;
+}
+/** Lightweight conflict record returned by listings. */
+export interface SyncConflictSummary {
+    readonly id: SyncConflictId;
+    readonly replicaId: ReplicaId;
+    readonly datasetId: string;
+    readonly sourceId?: SourceId;
+    readonly layerId?: string | number;
+    /** Shared with the temporal contracts (#227) so a conflict's feature can be
+     * fed straight into a temporal feature timeline. */
+    readonly featureId: FeatureId;
+    readonly kind: SyncConflictKind;
+    readonly status: SyncConflictStatus;
+    readonly clientOperation: SyncConflictOperation;
+    readonly serverOperation: SyncConflictOperation;
+    readonly detectedAt: string;
+    /** Number of conflicting fields; geometry counts separately. */
+    readonly fieldConflictCount: number;
+    readonly hasGeometryConflict: boolean;
+    readonly client?: SyncActor;
+    readonly device?: SyncDevice;
+}
+/** Full three-way conflict detail for manual review. */
+export interface SyncConflictDetail extends SyncConflictSummary {
+    readonly serverGen?: ServerGenerationCursor;
+    readonly base: ConflictFeatureState;
+    readonly clientState: ConflictFeatureState;
+    readonly serverState: ConflictFeatureState;
+    readonly fieldConflicts: ReadonlyArray<FieldConflict>;
+    readonly geometryConflict?: GeometryConflictSummary;
+    readonly resolutionOptions: ReadonlyArray<ConflictResolutionOption>;
+    /** Resolution recorded once the conflict reaches a terminal state. */
+    readonly resolution?: SyncConflictResolutionRecord;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** A resolution submitted by a reviewer. */
+export interface SyncConflictResolution {
+    readonly conflictId: SyncConflictId;
+    readonly choice: ConflictResolutionChoice;
+    /** Required when `choice` is `merge`: the field values to commit. */
+    readonly mergedAttributes?: Readonly<Record<string, unknown>>;
+    readonly mergedGeometry?: unknown;
+    readonly note?: string;
+    readonly resolvedBy?: SyncActor;
+}
+/** Server acknowledgement of an applied resolution. */
+export interface SyncConflictResolutionRecord {
+    readonly conflictId: SyncConflictId;
+    readonly choice: ConflictResolutionChoice;
+    readonly status: "resolved" | "discarded";
+    readonly resolvedAt: string;
+    readonly resolvedBy?: SyncActor;
+    /** Server generation produced by committing the resolution. */
+    readonly serverGen?: ServerGenerationCursor;
+    readonly note?: string;
+}
+/** Pageable request for the replica listing. */
+export interface ListReplicasRequest {
+    readonly datasetId?: string;
+    readonly sourceId?: SourceId;
+    readonly states?: ReadonlyArray<ReplicaState>;
+    readonly ownerId?: string;
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly signal?: AbortSignal;
+}
+/** Pageable request for conflict listings. */
+export interface ListConflictsRequest {
+    readonly replicaId?: ReplicaId;
+    readonly datasetId?: string;
+    readonly statuses?: ReadonlyArray<SyncConflictStatus>;
+    readonly kinds?: ReadonlyArray<SyncConflictKind>;
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly signal?: AbortSignal;
+}
+/** A page of results plus an optional continuation cursor. */
+export interface SyncPage<T> {
+    readonly items: ReadonlyArray<T>;
+    readonly cursor?: string;
+    readonly totalCount?: number;
+}
+/** Result of submitting a batch of resolutions. */
+export interface BatchConflictResolutionResult {
+    readonly records: ReadonlyArray<SyncConflictResolutionRecord>;
+    /** Conflicts that could not be resolved, with a reason. */
+    readonly failures: ReadonlyArray<{
+        readonly conflictId: SyncConflictId;
+        readonly reason: string;
+    }>;
+}
+/**
+ * Transport-neutral contract the client drives. A fixture transport ships with
+ * the SDK; a Connect/HTTP adapter can implement the same surface when the
+ * server endpoints land.
+ */
+export interface ReplicaSyncTransport {
+    /** Capabilities for a dataset (or the default source within it). */
+    capabilities(datasetId: string, sourceId?: string): Promise<ReplicaSyncCapabilities>;
+    listReplicas(request?: ListReplicasRequest): Promise<SyncPage<DisconnectedReplica>>;
+    getReplica(replicaId: ReplicaId, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<DisconnectedReplica>;
+    listConflicts(request?: ListConflictsRequest): Promise<SyncPage<SyncConflictSummary>>;
+    getConflict(conflictId: SyncConflictId, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<SyncConflictDetail>;
+    resolveConflict(resolution: SyncConflictResolution): Promise<SyncConflictResolutionRecord>;
+    resolveConflicts(resolutions: ReadonlyArray<SyncConflictResolution>): Promise<BatchConflictResolutionResult>;
+}
+//# sourceMappingURL=types.d.ts.map