obsidian-livesync/docs/adr/2026_07_adaptive_journal_webdav.md

Architectural Decision Record: Gate Adaptive WebDAV with an Endpoint Safety Check

Status

Proposed as an experimental provider after the S3 Adaptive path has completed adapter, CLI, host, and real-host acceptance.

Context

WebDAV exposes an object-shaped interface suitable for immutable packs, but method support and conditional semantics vary across servers, gateways, reverse proxies, and authentication layers. A server can advertise WebDAV while failing binary fidelity, replacing an object despite If-None-Match: *, returning incomplete listings, or ignoring Range.

The common protocol decision is recorded in Adaptive Journal as an explicit protocol. The pack format, flat object mapping, and detailed safety-check sequence are specified in the Adaptive Journal Sync design.

Decision

Adaptive WebDAV uses the same immutable pack and catalogue semantics proven by S3, with a WebDAV-specific flat object mapping inside the configured collection. Logical writer ordering comes from the host ID, writer epoch, and dense sequence embedded in authenticated records. Correctness does not depend on a server-provided startAfter order.

Before a new Adaptive repository becomes writable, a non-destructive endpoint safety checker exercises random reserved probe keys and reports observed semantic capabilities:

• binary write and exact read-back;
• read-after-write visibility;
• complete collection listing for the probe keys;
• If-None-Match: * preventing replacement;
• delete visibility; and
• exact byte-range behaviour, reported separately as optional.

The checker is an implementation acceptance target for compatible servers, not a claim that every WebDAV server must support Adaptive Journal. It touches no repository objects, attempts to remove every probe, reports incomplete cleanup, and never interprets authentication, permission, timeout, malformed response, or server failure as absence.

Conditional create, binary fidelity, complete listing, read-after-write visibility, and delete visibility are required. Range remains optional. The user selects whole-pack or Range retrieval based on their endpoint and own latency and throughput preference; the checker does not benchmark or recommend a policy.

Successful mutations do not receive unconditional confirmation requests. An ambiguous response is classified as verify-first, and the exact immutable key is read before retrying. The existing opaque WebDAV layout and Adaptive layout are detected separately; a mismatch requires a remote rebuild or another namespace.

Staged acceptance

Adapter and Commonlib integration

Unit tests own HTTP status classification, conditional-create verification, flat-name round trips, complete listing, probe isolation, cleanup reporting, Range validation, and whole-pack fallback. A disposable WebDAV integration runs the safety checker before exercising Adaptive Metadata and Chunk synchronisation.

CLI end-to-end acceptance

The built CLI applies an Adaptive WebDAV Setup URI to a second independent database and synchronises text and binary Chunk-backed files through a real disposable server. One client uses whole-pack retrieval; Range is added to this layer only when the selected test server proves it. The CLI test does not repeat the complete endpoint capability matrix.

Host settings and UI

The WebDAV dialogue exposes Adaptive mode only with clear capability-check results. It persists the expected repository ID and the selected retrieval policy, defaults to whole-pack, and reports that Range is optional. Focused tests own profile and Setup URI preservation without contacting a server.

Real-host end-to-end acceptance

One real-Obsidian workflow uses the same known disposable WebDAV implementation, runs the safety gate, and proves a representative Chunk-backed transfer. Servers outside that fixture are diagnosed by the checker rather than added to a large real-host matrix.

Alternatives rejected

Trust advertised WebDAV methods

Method advertisement does not prove the conditional, listing, visibility, and byte semantics required for immutable publication.

Treat Range as mandatory

Whole-pack retrieval is correct and often competitive for throughput. Requiring Range would exclude otherwise safe servers for an optional optimisation.

Add server-specific compatibility branches

The remote may be any implementation or proxy composition. Semantic checks produce a maintainable contract, while a growing server-name table would remain incomplete and become stale.

Consequences

• WebDAV remains experimental because suitability is endpoint-specific.
• The safety checker gives a concrete reason when a server cannot host Adaptive Journal.
• Common object-pack behaviour is inherited from the earlier S3 boundary, keeping WebDAV-specific tests focused on HTTP semantics and name mapping.
• Optional Range support can improve request efficiency without becoming a data-availability requirement.