Sync polish round 2: settlement serialization, history durability, retired-enrollment fencing, keyboard and narrow layouts

docs/sync-ux-acceptance.md

@@ -0,0 +1,28 @@
+# Sync UI acceptance in isolated Obsidian
+
+`test/workspaceView.test.ts` and `test/settingsTab.test.ts` exercise the real renderers and handlers in jsdom. Run `npm test` and `npm run lint`.
+
+For visual checks, `scripts/test-sync-layout.cjs` drives an **isolated, disposable** Obsidian instance over Playwright CDP. Never attach it to a personal vault. It stops background sync and injects presentation state; it does not enroll or call a live Connect service.
+
+## Prepare
+
+1. Build the plugin and copy `main.js`, `manifest.json`, and `styles.css` into a disposable vault's `.obsidian/plugins/mdbase-obsidian/`. Enable the plugin in that vault.
+2. Use a separate Obsidian app copy and profile. The profile's `obsidian.json` should list only the disposable vault, with `open: true`. Launch with `--no-sandbox --ozone-platform=wayland --user-data-dir=<profile> --password-store=basic --remote-debugging-port=<port>`.
+3. Create the opt-in marker `.obsidian/mdbase-ux-disposable` in the disposable vault. The script refuses unmarked vaults and checks the attached vault's exact path before injecting state.
+4. Make that isolated window visible so Wayland can paint screenshots. Do not drive another agent's window.
+
+## Run
+
+```sh
+MDBASE_UX_CDP_URL=http://127.0.0.1:42001 \
+MDBASE_UX_VAULT=/absolute/path/to/disposable-vault \
+MDBASE_UX_SHOTS=/absolute/path/to/screenshots \
+MDBASE_UX_PLAYWRIGHT=/absolute/path/to/node_modules/@playwright/test \
+node scripts/test-sync-layout.cjs after-layout
+```
+
+`MDBASE_UX_PLAYWRIGHT` can be omitted if Playwright is already resolvable. It is not a plugin runtime dependency.
+
+The audit captures 14 states at 1100px and 390px, in dark and light themes: healthy, offline, sign-in, copied device, paused, unexpected failure, progress, first-sync review, deletion-burst review, rebuild, unresolved conflict, pinned conflict history, enrollment, and local upload. Desktop sidebars are collapsed for realistic narrow panes. Assertions reject horizontal overflow and primary/dismiss targets below 44px in narrow panes. Long, unbroken paths are intentional. `*-checks.json` records the measured bounds; the command exits nonzero on a regression.
+
+Review the PNGs as well as the assertions. Diff panels may scroll horizontally within their own surface; the workspace itself must not. Stop the isolated instance after testing and discard its app/profile/vault. Injected profile state is ephemeral and must never be saved as real credentials.

main.ts

@@ -36,7 +36,7 @@ import {
 import type { StoredTypeDraft, TypeEditorModel } from "./src/typeEditorTypes";
 import {
   ConnectSyncController,
-  normalizeSelectiveSync,
+  normalizeMirrorProfile,
   type MirrorProfile,
 } from "./src/connectSync";
 import {
@@ -93,24 +93,6 @@ const DEFAULT_SETTINGS: MdbasePluginSettings = {
 /** Vault-scoped device storage key; Obsidian keeps it out of the vault and out of plugin data. */
 const DEVICE_ID_KEY = "mdbase-sync-device-id";
 
-function isMirrorProfile(value: unknown): value is MirrorProfile {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-  const profile = value as Partial<MirrorProfile>;
-  return profile.version === 1
-    && typeof profile.syncUrl === "string"
-    && typeof profile.controlUrl === "string"
-    && typeof profile.collectionId === "string"
-    && typeof profile.replicaId === "string"
-    && (profile.mode === "read_only" || profile.mode === "read_write")
-    && typeof profile.name === "string"
-    && typeof profile.enrollmentId === "string"
-    && typeof profile.accessTokenExpiresAt === "string"
-    && (profile.selectiveSync === undefined || (
-      Array.isArray(profile.selectiveSync.file_classes)
-      && Array.isArray(profile.selectiveSync.excluded_folders)
-    ));
-}
-
 function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -356,16 +338,7 @@ export default class MdbasePlugin extends Plugin {
       this.settings.autoSync = true;
       this.settings.syncSettingsVersion = 2;
     }
-    if (!isMirrorProfile(this.settings.mirrorProfile)) {
-      this.settings.mirrorProfile = null;
-    } else {
-      try {
-        this.settings.mirrorProfile.selectiveSync = normalizeSelectiveSync(this.settings.mirrorProfile.selectiveSync);
-      } catch {
-        // Fail closed for corrupted legacy data without discarding enrollment.
-        this.settings.mirrorProfile.selectiveSync = normalizeSelectiveSync();
-      }
-    }
+    this.settings.mirrorProfile = normalizeMirrorProfile(this.settings.mirrorProfile);
     if (!this.settings.typeDrafts || typeof this.settings.typeDrafts !== "object" || Array.isArray(this.settings.typeDrafts)) {
       this.settings.typeDrafts = {};
     }
@@ -1071,7 +1044,7 @@ export default class MdbasePlugin extends Plugin {
    * echoes. The scheduler syncs once the burst of edits settles.
    */
   private observeLocalMirrorChange(path: string): void {
-    if (!this.getMirrorProfile() || this.connectSync.isEngineWrite(path)) return;
+    if (!this.getMirrorProfile() || this.connectSync.consumeEngineWrite(path)) return;
     const normalized = normalizePath(path);
     const reservedFolders = [this.app.vault.configDir, ".mdbase", ".trash", ".git"];
     if (reservedFolders.some((folder) => normalized === folder || normalized.startsWith(`${folder}/`))) return;

patches/@mdbase-dev+connect-sync+0.1.0-beta.120.patch

@@ -1,8 +1,8 @@
 diff --git a/node_modules/@mdbase-dev/connect-sync/dist/directory-mirror.d.ts b/node_modules/@mdbase-dev/connect-sync/dist/directory-mirror.d.ts
-index dd5830c..e774a50 100644
+index dd5830c..868ba93 100644
 --- a/node_modules/@mdbase-dev/connect-sync/dist/directory-mirror.d.ts
 +++ b/node_modules/@mdbase-dev/connect-sync/dist/directory-mirror.d.ts
-@@ -34,6 +34,11 @@ export declare class DirectoryMirror<Frontmatter extends JsonObject = JsonObject
+@@ -34,12 +34,18 @@ export declare class DirectoryMirror<Frontmatter extends JsonObject = JsonObject
       * into the durable base before the checkpoint action runs.
       */
      private initialUnchangedState;
@@ -14,11 +14,27 @@ index dd5830c..e774a50 100644
      status(): Promise<MirrorStatus>;
      checkpointStatus(): Promise<MirrorStatus>;
      private checkpointStatusUnlocked;
+     authorityPromotionManifest(): Promise<AuthorityPromotionManifest>;
+     previewInitialization(): Promise<MirrorInitializationPreview>;
+-    resolveConflict(identity: string, decisionId: string, resolution: "local" | "remote"): Promise<void>;
++    /** An optional merged record is written conditionally before the durable conflict is cleared. */
++    resolveConflict(identity: string, decisionId: string, resolution: "local" | "remote", mergedDocument?: string): Promise<void>;
+     private resolveConflictUnlocked;
+     private installRemoteRecord;
+     private installRemoteFile;
 diff --git a/node_modules/@mdbase-dev/connect-sync/dist/directory-mirror.js b/node_modules/@mdbase-dev/connect-sync/dist/directory-mirror.js
-index a9018ff..80cc6e3 100644
+index a9018ff..ba68459 100644
 --- a/node_modules/@mdbase-dev/connect-sync/dist/directory-mirror.js
 +++ b/node_modules/@mdbase-dev/connect-sync/dist/directory-mirror.js
-@@ -68,7 +68,7 @@ export class DirectoryMirror {
+@@ -8,6 +8,7 @@ import { checkpointMirrorStatus, mirrorStatusFromPlan } from "./mirror-status.js
+ import { PlanOnlyMirrorInspector } from "./sync-inspector.js";
+ import { PlanOnlySyncExecutor } from "./sync-executor.js";
+ import { PlanRevalidator } from "./sync-revalidator.js";
++import { runtimeDocumentRevision } from "./mirror-format.js";
+ import { abandonStaleBatch, prepareSyncBatch } from "./sync-journal.js";
+ import { advanceEmptySyncCheckpoint, advanceSyncCheckpoint } from "./sync-checkpoint.js";
+ import { loadMirrorSnapshot } from "./sync-snapshot-loader.js";
+@@ -68,7 +69,7 @@ export class DirectoryMirror {
              }
              if (state?.last_completed_plan === plan.fingerprint) {
                  const checkpoint = checkpointMirrorStatus(state, this.mode);
@@ -27,7 +43,7 @@ index a9018ff..80cc6e3 100644
              }
              const inspection = await this.inspectDetailed(state);
              if (inspection.plan.fingerprint !== plan.fingerprint) {
-@@ -126,6 +126,9 @@ export class DirectoryMirror {
+@@ -126,6 +127,9 @@ export class DirectoryMirror {
              })
          }).execute(state, signal);
          if (result.status !== "effects_complete") {
@@ -37,7 +53,7 @@ index a9018ff..80cc6e3 100644
              const checkpoint = checkpointMirrorStatus(state, this.mode);
              return mirrorApplyResult(result.status === "blocked" ? "failed" : result.status, batch.plan, checkpoint, result.completed, result.failure);
          }
-@@ -135,7 +138,8 @@ export class DirectoryMirror {
+@@ -135,7 +139,8 @@ export class DirectoryMirror {
          const checkpoint = checkpointMirrorStatus(state, this.mode);
          const attention = checkpoint.conflicts.length > 0
              || checkpoint.local_issues.length > 0
@@ -47,7 +63,7 @@ index a9018ff..80cc6e3 100644
          return mirrorApplyResult(attention ? "attention" : "applied", plan, checkpoint, result.completed);
      }
      inspectDetailed(state) {
-@@ -196,13 +200,21 @@ export class DirectoryMirror {
+@@ -196,13 +201,21 @@ export class DirectoryMirror {
              planned_conflicts: {}
          };
      }
@@ -75,6 +91,90 @@ index a9018ff..80cc6e3 100644
      }
      async checkpointStatus() {
          return this.lease.runExclusive(() => this.checkpointStatusUnlocked());
+@@ -263,10 +276,10 @@ export class DirectoryMirror {
+                 .map((issue) => ({ code: "invalid_frontmatter", message: issue.message, path: issue.path }))
+         };
+     }
+-    async resolveConflict(identity, decisionId, resolution) {
+-        await this.lease.runExclusive(() => this.resolveConflictUnlocked(identity, decisionId, resolution));
++    async resolveConflict(identity, decisionId, resolution, mergedDocument) {
++        await this.lease.runExclusive(() => this.resolveConflictUnlocked(identity, decisionId, resolution, mergedDocument));
+     }
+-    async resolveConflictUnlocked(identity, decisionId, resolution) {
++    async resolveConflictUnlocked(identity, decisionId, resolution, mergedDocument) {
+         if (this.mode !== "read_write") {
+             throw new SyncError("mirror_read_only", "Receive-only mirrors have no writable conflicts.");
+         }
+@@ -280,12 +293,9 @@ export class DirectoryMirror {
+         }
+         if ((planned.decision_id ?? "") !== decisionId)
+             throw staleConflict();
+-        const revalidator = new PlanRevalidator(this.fileSystem, this.runtime);
+-        if (planned.local.state === "exact") {
+-            await revalidator.validateExpected(planned.local);
+-        }
+-        else if (planned.remote.state === "exact") {
+-            await revalidator.validateExpectedAt(planned.remote.object.path, planned.local);
++        if (mergedDocument !== undefined && (resolution !== "local"
++            || planned.entity !== "record" || planned.local.state !== "exact")) {
++            throw new SyncError("invalid_conflict_resolution", "A merged document requires an exact local record conflict.");
+         }
+         const snapshot = await loadMirrorSnapshot(this.replicaId, this.transport, this.mode, this.selectiveSync, this.runtime);
+         const currentRecord = planned.entity === "record"
+@@ -299,6 +309,15 @@ export class DirectoryMirror {
+             : fileStateMatches(planned.remote, currentFile);
+         if (!remoteMatches)
+             throw staleConflict();
++        // Snapshot loading can take arbitrarily long. Fence the decision's local
++        // bytes after that network wait, not before it.
++        const revalidator = new PlanRevalidator(this.fileSystem, this.runtime);
++        if (planned.local.state === "exact") {
++            await revalidator.validateExpected(planned.local);
++        }
++        else if (planned.remote.state === "exact") {
++            await revalidator.validateExpectedAt(planned.remote.object.path, planned.local);
++        }
+         if (resolution === "remote") {
+             if (planned.entity === "record") {
+                 await this.installRemoteRecord(state, identity, currentRecord);
+@@ -307,6 +326,17 @@ export class DirectoryMirror {
+                 await this.installRemoteFile(state, identity, currentFile);
+             }
+         }
++        if (mergedDocument !== undefined) {
++            const path = planned.local.object.path;
++            const expected = await this.fileSystem.read(path);
++            if (expected === null || runtimeDocumentRevision(expected, this.runtime) !== planned.local.object.payload_revision) {
++                throw staleConflict();
++            }
++            // Persist both halves in the merged file before clearing the durable
++            // conflict. A crash or failed write must never authorize an upload
++            // of the original, unmerged local document over the hosted edit.
++            await this.fileSystem.write(path, mergedDocument, expected);
++        }
+         delete state.planned_conflicts?.[identity];
+         if (resolution === "remote")
+             delete state.local_bindings?.[identity];
+@@ -314,14 +344,12 @@ export class DirectoryMirror {
+     }
+     async installRemoteRecord(state, identity, current) {
+         if (current) {
+-            const conflict = state.planned_conflicts?.[identity];
+-            const acceptedDocument = await this.fileSystem.read(current.path);
+-            const pathBelongsToIdentity = state.records[identity]?.path === current.path
+-                || (conflict?.local.state === "exact" && conflict.local.object.path === current.path);
++            // Accept only the local version named by the conflict decision. Never
++            // authorize whatever bytes happen to be present after an async reread.
++            const local = state.planned_conflicts?.[identity]?.local;
+             await this.materializer.put(state, current, {
+-                inspectionPreflighted: false,
+-                ...(pathBelongsToIdentity && acceptedDocument !== null
+-                    ? { acceptedHash: this.runtime.digest(acceptedDocument) }
++                ...(local?.state === "exact" && local.object.path === current.path
++                    ? { acceptedHash: local.object.payload_revision.replace(/^sha256:/u, "") }
+                     : {})
+             });
+             return;
 diff --git a/node_modules/@mdbase-dev/connect-sync/dist/mirror-materializer.js b/node_modules/@mdbase-dev/connect-sync/dist/mirror-materializer.js
 index 6936f79..64b0670 100644
 --- a/node_modules/@mdbase-dev/connect-sync/dist/mirror-materializer.js

patches/README.md

@@ -48,6 +48,22 @@ addition is the optional `ancestor_document` below):
 - `sync-executor.js`: the special receive-only malformed-frontmatter repair
   allowance applies only to that explicitly identified target, never every
   download in a partial plan. Conditional writes remain enforced.
+- `directory-mirror.js`: a hosted conflict resolution accepts only the inspected
+  local document revision, not whatever bytes happen to exist after loading the
+  authority snapshot. A user edit or recreated file during that await leaves
+  the decision stale instead of silently overwriting bytes absent from the copy.
+  Ported exactly from mdbase-connect `56dabd74` (local revalidation after the
+  snapshot, decision-bound `acceptedHash`). Integration regression:
+  `test/connectSync.settlement.test.ts`.
+- `directory-mirror.js` / `.d.ts`: `resolveConflict(identity, decisionId, "local",
+  mergedDocument?)` optionally persists a merged record with the adapter's
+  conditional write before clearing its durable conflict. Without this ordering,
+  a hard restart between clearing and the plugin's write could upload unmerged
+  local text over the hosted edit. Only an exact local record accepts a merged
+  document; a failed write leaves the conflict intact. No protocol or persisted
+  state change. This additional SDK API needs an upstream source port before
+  upgrading/removing the patch. Regressions simulate restart at the write
+  boundary, disk-full failure, and a user edit during the atomic write.
 - `directory-mirror.js`: partial completion reports attention, not failure or
   falsely complete synchronization, while preserving its unresolved diagnostics.
 - `directory-mirror.js`: release stale batches at the SDK's existing safe journal