@vrtmrz/livesync-commonlib 0.1.0-rc.7 → 0.1.0-rc.9

package/dist/common/models/setting.lifecycle.d.ts

@@ -2,6 +2,7 @@ import type { ObsidianLiveSyncSettings } from "./setting.type.js";
 export declare const SettingsMigrationReviewCodes: {
     readonly LegacyUpdatePending: "legacy-update-review-pending";
     readonly FutureSchema: "settings-schema-newer-than-runtime";
+    /** @deprecated Missing legacy values are now normalised to false and do not emit this reason. */
     readonly FilenameCaseSensitivityUnresolved: "filename-case-sensitivity-unresolved";
 };
 export type SettingsMigrationReviewCode = (typeof SettingsMigrationReviewCodes)[keyof typeof SettingsMigrationReviewCodes];

package/dist/common/models/setting.lifecycle.js

@@ -7,6 +7,7 @@ import {
 const SettingsMigrationReviewCodes = {
   LegacyUpdatePending: "legacy-update-review-pending",
   FutureSchema: "settings-schema-newer-than-runtime",
+  /** @deprecated Missing legacy values are now normalised to false and do not emit this reason. */
   FilenameCaseSensitivityUnresolved: "filename-case-sensitivity-unresolved"
 };
 const SETTINGS_MIGRATIONS = [
@@ -43,6 +44,10 @@ function storedSettingVersion(settings) {
 function isBlankSettings(settings) {
   return settings === void 0 || Object.keys(settings).length === 0;
 }
+function inferLegacyConfiguredState(settings) {
+  const completed = { ...SETTINGS_SCHEMA_DEFAULTS, ...settings };
+  return JSON.stringify(completed) !== JSON.stringify(SETTINGS_SCHEMA_DEFAULTS);
+}
 function prepareSettingsForLoad(storedSettings) {
   if (isBlankSettings(storedSettings)) {
     return {
@@ -93,20 +98,19 @@ function prepareSettingsForLoad(storedSettings) {
       `No setting migration reaches schema ${CURRENT_SETTING_VERSION} from schema ${sourceVersion}.`
     );
   }
-  if (typeof migrated.handleFilenameCaseSensitive !== "boolean") {
-    reviewReasons.push({
-      code: SettingsMigrationReviewCodes.FilenameCaseSensitivityUnresolved,
-      fromVersion: sourceVersion,
-      toVersion: targetVersion
-    });
+  const normalisedConfiguredState = migrated.isConfigured === void 0;
+  if (normalisedConfiguredState) {
+    migrated = { ...migrated, isConfigured: inferLegacyConfiguredState(source) };
   }
+  const normalisedFilenameCase = typeof migrated.handleFilenameCaseSensitive !== "boolean";
+  if (normalisedFilenameCase) migrated = { ...migrated, handleFilenameCaseSensitive: false };
   return {
     settings: cloneSettings(migrated, SETTINGS_SCHEMA_DEFAULTS),
     sourceVersion,
     targetVersion,
     isNewVault: false,
     isFromFutureSchema: false,
-    changed: sourceVersion !== targetVersion,
+    changed: sourceVersion !== targetVersion || normalisedConfiguredState || normalisedFilenameCase,
     requiresSyncReview: reviewReasons.length > 0,
     reviewReasons
   };

package/dist/platform/node/storage.d.ts

@@ -2,7 +2,12 @@ import type { UXDataWriteOptions, UXStat } from "../../common/types.js";
 import type { IStorageAdapter } from "../../serviceModules/adapters/IStorageAdapter.js";
 export type NodeStorageStat = UXStat;
 export interface CreateNodeStorageOptions {
-    /** Absolute or process-relative directory which bounds every adapter operation. */
+    /**
+     * Host-selected root directory. Adapter paths are resolved relative to this root.
+     *
+     * The host owns this trust boundary. The adapter is not a filesystem sandbox against
+     * an untrusted local process which can replace path components concurrently.
+     */
     rootPath: string;
 }
 /** Rooted storage adapter backed by Node's file-system APIs. */

package/docs/platform-storage.md

@@ -39,7 +39,9 @@ await storage.write('notes/example.md', '# Example');
 
 `rootPath` may be absolute or process-relative. The host should normally resolve and validate configuration before constructing the adapter.
 
-The Node adapter does not follow symbolic links in adapter paths. A path containing a symbolic link is rejected, including when the link points to another location below `rootPath`, so every operation retains one unambiguous rooted-storage boundary. Its concrete `rename(sourcePath, targetPath)` operation preserves this boundary while providing the atomic rename expected by Node hosts.
+The Node adapter rejects symbolic-link components which it observes in an adapter path before an operation. File opens also use `O_NOFOLLOW` for the final component where the platform exposes that flag. These checks protect against invalid paths and symbolic links which already exist when an operation begins. Its concrete `rename(sourcePath, targetPath)` operation validates both paths before providing the atomic rename expected by Node hosts.
+
+The host-selected `rootPath` is a trust boundary, not an operating-system filesystem sandbox. The adapter assumes that an untrusted local process cannot replace that root or its descendants concurrently with an operation. A host which grants another local actor write access to the tree must not rely on the adapter as a privilege boundary.
 
 ## Shared path contract
 

package/docs/settings-lifecycle.md

@@ -20,8 +20,25 @@ const initialSettings = createNewVaultSettings();
 
 The recommended base currently selects a 50 MB maximum synchronised file size, Rabin–Karp chunk splitting, Plug-in Sync V2, case-insensitive file-name handling, and E2EE V2. Chunk revisions are always derived from their content; the obsolete `doNotUseFixedRevisionForChunks` stored key is retained only for compatibility and is not a recommendation or tweak. The recommended base does not enable synchronisation or encryption on behalf of the user.
 
+Compared with the conservative stored-setting fallbacks, the current new-Vault object has exactly two semantic differences:
+
+| Setting | Existing stored setting is absent | New Vault |
+| --- | --- | --- |
+| `usePluginSyncV2` | `false` | `true` |
+| `handleFilenameCaseSensitive` | normalised from the legacy absent value to `false` | `false` |
+
+The other headline recommendations are already the conservative fallbacks: `syncMaxSizeInMB` is 50, `chunkSplitterVersion` is `v3-rabin-karp`, and `E2EEAlgorithm` is `v2`. Data Compression, Eden, V1 dynamic iteration, the legacy IndexedDB adapter, Hidden File Sync, and automatic synchronisation remain disabled when their stored values are absent. Explicit stored values take precedence.
+
 Apply a remote-specific preferred object only while configuring that remote. Do not merge it into an existing stored configuration merely because the remote type can be inferred. The self-hosted CouchDB profile uses a chunk-size coefficient of 60, matching the Doctor check for Rabin–Karp databases; Cloudant retains its service-specific value of 0.
 
+| Explicitly selected remote | `customChunkSize` | `concurrencyOfReadChunksOnline` | `minimumIntervalOfReadChunksOnline` |
+| --- | ---: | ---: | ---: |
+| Cloudant | 0 | 100 | 333 |
+| Self-hosted CouchDB | 60 | 30 | 25 |
+| Object Storage | 10 | 30 | 25 |
+
+These are setup-time recommendations, not upgrade migrations. Selecting or detecting a remote does not apply them to an existing configuration unless the person is actively configuring that remote.
+
 ## Loading existing settings
 
 `prepareSettingsForLoad` detects a blank store, completes stored settings with conservative schema fallbacks, runs ordered schema migrations, and reports the result separately from the settings value:
@@ -43,7 +60,13 @@ if (prepared.requiresSyncReview) {
 
 Explicit stored values take precedence over every fallback. A migration therefore preserves synchronisation switches and other user choices unless a migration step documents a deliberate transformation.
 
-An existing settings store without an explicit `handleFilenameCaseSensitive` value reports `filename-case-sensitivity-unresolved` and leaves the value unset. The host must keep synchronisation paused until the user makes an explicit compatibility decision. An explicit `true` or `false` value is preserved. New Vaults select case-insensitive handling (`false`).
+An existing settings store without an explicit `handleFilenameCaseSensitive` value is normalised to `false` and saved. This preserves the effective behaviour of earlier releases, where an absent value followed the case-insensitive branch. An explicit `true` or `false` value is preserved. New Vaults also select case-insensitive handling (`false`).
+
+`isConfigured` has a separate compatibility rule from new-Vault initialisation. For a blank store, the standard service keeps the runtime unconfigured. For a non-empty legacy document without the flag, Commonlib repeats the pre-1.0 inference: a document which is equivalent to the conservative defaults remains `false`, while a stored non-default value is evidence for `true`. The inferred boolean is saved. An explicit boolean is preserved. This rule does not make a non-empty document eligible for new-Vault recommendations.
+
+Two other values deliberately remain unset until their owning lifecycle supplies evidence: `autoAcceptCompatibleTweak` represents that no auto-accept decision has been made, and `tweakModified` represents that no tweak-change timestamp has been recorded. They are not implicit boolean defaults and are not normalised by the settings migration.
+
+`SettingsMigrationReviewCodes.FilenameCaseSensitivityUnresolved` remains as a deprecated compatibility export for release-candidate consumers, but `prepareSettingsForLoad` no longer emits it.
 
 The standard Commonlib `SettingService` performs this preparation automatically. Hosts which use that service can inspect `getSettingsMigrationState()` after `loadSettings()` instead of calling the function themselves.
 
@@ -57,6 +80,6 @@ The settings schema version is independent of the package version and of any rem
 
 ## Tests owned by Commonlib
 
-The settings lifecycle unit tests cover blank stores, representative legacy choices, migration idempotence, unresolved file-name case policy, legacy review state, future-schema downgrade protection, and the distinction between new-Vault recommendations and stored-setting fallbacks. The packed-package test imports the focused `/settings` entry from a clean consumer and checks its declarations and runtime exports.
+The settings lifecycle unit tests cover blank stores, representative legacy choices, migration idempotence, legacy file-name case normalisation, legacy review state, future-schema downgrade protection, and the distinction between new-Vault recommendations and stored-setting fallbacks. The packed-package test imports the focused `/settings` entry from a clean consumer and checks its declarations and runtime exports.
 
 Hosts remain responsible for testing when setup is classified as new, how local review acknowledgement is stored, how replication is gated, and how their settings interface presents the result.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.9",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "license": "MIT",