@vrtmrz/livesync-commonlib 0.1.0-rc.0 → 0.1.0-rc.10

package/docs/remote-configurations.md

@@ -0,0 +1,63 @@
+# Remote configuration profiles
+
+Commonlib represents saved remote connections as independently named profiles. The profile map is the persisted source for multiple-remote selection. Existing CouchDB, Object Storage, and P2P fields remain the runtime projection consumed by compatibility services.
+
+Use the focused entry point for new profile-management code:
+
+```ts
+import {
+    upsertRemoteConfigurationInPlace,
+    type RemoteConfiguration,
+} from "@vrtmrz/livesync-commonlib/remote-configurations";
+import { createNewVaultSettings } from "@vrtmrz/livesync-commonlib/settings";
+
+const settings = createNewVaultSettings();
+Object.assign(settings, {
+    couchDB_URI: "https://couch.example",
+    couchDB_USER: "alice",
+    couchDB_PASSWORD: "secret",
+    couchDB_DBNAME: "notes",
+});
+
+const profile: RemoteConfiguration = upsertRemoteConfigurationInPlace(settings, "couchdb", {
+    activate: true,
+});
+```
+
+The helper serialises the connection fields into the profile URI. When `activate` is true, it selects that profile through `activeConfigurationId` and projects the profile back onto the compatibility fields. The host still owns persistence, restart policy, credential acquisition, and user confirmation.
+
+## Identity and display names
+
+Profile IDs are opaque identity. Omit `id` to allocate a new one and preserve every existing profile. Pass a known `id` only when deliberately updating that profile.
+
+Display names are presentation, not identity. When `name` is omitted, Commonlib proposes a concise type-specific name such as `CouchDB couch.example`, `S3 notes`, or `P2P team-room`. It adds a numeric suffix when that display name is already present. A host may let users rename profiles without changing their IDs or selections.
+
+There is no special profile named or identified as `default`. The selected main remote is represented only by `activeConfigurationId`.
+
+## Main and P2P selections
+
+`activeConfigurationId` selects the main remote used by ordinary replication. `P2P_ActiveRemoteConfigurationId` independently selects the profile used by P2P features.
+
+- Use `{ activate: true }` for a CouchDB or Object Storage profile selected as the main remote.
+- Use `{ activate: true, activateForP2P: true }` when P2P is the main remote.
+- Use `{ activateForP2P: true }` to select a P2P profile without changing the main remote.
+
+Selecting a profile updates the compatibility fields immediately. Existing replication services may therefore continue to consume those fields while profile-aware hosts treat the profile map and selection IDs as authoritative persisted state.
+
+## Import and migration boundary
+
+A modern Setup URI or another settings transport should preserve `remoteConfigurations`, profile IDs, display names, `activeConfigurationId`, and `P2P_ActiveRemoteConfigurationId` exactly.
+
+An older settings payload may contain only the flat remote fields. The standard `SettingService` recognises that shape when the profile map is empty and migrates the configured connections into explicitly labelled `legacy-*` profiles. This is a compatibility path, not the recommended way to create a new profile. New setup flows should call the focused API directly.
+
+If a settings payload already contains profiles, legacy migration does not create or replace any entry. A host which writes only flat fields in that state would therefore fail to register a new connection; profile-aware setup code must upsert the profile explicitly.
+
+## Persistence and encryption
+
+The helper stores a plaintext connection URI in memory and marks the changed profile as unencrypted. The standard `SettingService` applies configured at-rest encryption when persisting settings. A host using a different persistence service must provide equivalent encryption and decryption policy itself.
+
+## Verification ownership
+
+Commonlib unit tests cover preserving existing profiles, generated-name collision handling, main-remote activation, and independent P2P selection. The packed-package test imports the focused entry from a clean consumer and checks its declarations and runtime exports.
+
+Hosts remain responsible for testing their dialogues, import classification, confirmation, Fetch or Rebuild scheduling, persistence, restart ordering, and real-runtime presentation.

package/docs/settings-lifecycle.md

@@ -0,0 +1,85 @@
+# Settings lifecycle
+
+Commonlib separates three values which older integrations commonly treated as one object:
+
+- `SETTINGS_SCHEMA_DEFAULTS` completes keys which are absent from stored settings. Its values remain conservative so that an upgrade does not silently change an existing choice.
+- `NEW_VAULT_SETTINGS` initialises a store which has never contained Self-hosted LiveSync settings. It includes the current recommended base values.
+- the `PREFERRED_SETTING_*` objects add remote-specific recommendations when a user explicitly selects Cloudant, self-hosted CouchDB, or Object Storage during setup.
+
+`DEFAULT_SETTINGS` remains an alias of `SETTINGS_SCHEMA_DEFAULTS` for compatibility. New code should choose the named contract which matches its operation.
+
+## Starting a new Vault
+
+Use `createNewVaultSettings()` only when the settings store is absent or empty, or when the user explicitly requests a factory reset. `NEW_VAULT_SETTINGS` exposes the values for inspection, while the factory prevents mutable nested settings from being shared between clients:
+
+```ts
+import { createNewVaultSettings } from "@vrtmrz/livesync-commonlib/settings";
+
+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:
+
+```ts
+import { prepareSettingsForLoad } from "@vrtmrz/livesync-commonlib/settings";
+
+const prepared = prepareSettingsForLoad(await host.loadSettings());
+const settings = prepared.settings;
+
+if (prepared.changed && !prepared.isFromFutureSchema) {
+    await host.saveSettings(settings);
+}
+
+if (prepared.requiresSyncReview) {
+    host.requestLocalSyncReview(prepared.reviewReasons);
+}
+```
+
+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 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.
+
+## Review and downgrade boundary
+
+A migration may report `requiresSyncReview` when automatic synchronisation should wait for a human decision. Commonlib reports that requirement but does not disable synchronisation settings, persist an acknowledgement, display a dialogue, or decide whether replication may proceed. Those are host-local responsibilities because one device must not acknowledge a safety review for another device through synchronised settings.
+
+Settings written by a schema newer than the running Commonlib version are completed for in-memory compatibility but are not assigned an older schema version. The result has `isFromFutureSchema: true`, `changed: false`, and a review reason. A host must not persist that completed object as a downgrade migration.
+
+The settings schema version is independent of the package version and of any remote data or protocol compatibility version. Increment it only when the stored settings shape requires an ordered migration.
+
+## Tests owned by Commonlib
+
+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.0",
+  "version": "0.1.0-rc.10",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "license": "MIT",
@@ -56,6 +56,16 @@
       "import": "./dist/rpc/index.js",
       "default": "./dist/rpc/index.js"
     },
+    "./remote-configurations": {
+      "types": "./dist/remoteConfigurations.d.ts",
+      "import": "./dist/remoteConfigurations.js",
+      "default": "./dist/remoteConfigurations.js"
+    },
+    "./settings": {
+      "types": "./dist/settings.d.ts",
+      "import": "./dist/settings.js",
+      "default": "./dist/settings.js"
+    },
     "./compat/API/processSetting": {
       "types": "./dist/API/processSetting.d.ts",
       "import": "./dist/API/processSetting.js",
@@ -91,11 +101,6 @@
       "import": "./dist/common/coreEnvVars.js",
       "default": "./dist/common/coreEnvVars.js"
     },
-    "./compat/common/i18n": {
-      "types": "./dist/common/i18n.d.ts",
-      "import": "./dist/common/i18n.js",
-      "default": "./dist/common/i18n.js"
-    },
     "./compat/common/logger": {
       "types": "./dist/common/logger.d.ts",
       "import": "./dist/common/logger.js",
@@ -116,16 +121,6 @@
       "import": "./dist/common/models/setting.const.js",
       "default": "./dist/common/models/setting.const.js"
     },
-    "./compat/common/models/setting.const.defaults": {
-      "types": "./dist/common/models/setting.const.defaults.d.ts",
-      "import": "./dist/common/models/setting.const.defaults.js",
-      "default": "./dist/common/models/setting.const.defaults.js"
-    },
-    "./compat/common/models/setting.const.preferred": {
-      "types": "./dist/common/models/setting.const.preferred.d.ts",
-      "import": "./dist/common/models/setting.const.preferred.js",
-      "default": "./dist/common/models/setting.const.preferred.js"
-    },
     "./compat/common/models/setting.type": {
       "types": "./dist/common/models/setting.type.d.ts",
       "import": "./dist/common/models/setting.type.js",
@@ -146,11 +141,6 @@
       "import": "./dist/common/models/tweak.definition.js",
       "default": "./dist/common/models/tweak.definition.js"
     },
-    "./compat/common/rosetta": {
-      "types": "./dist/common/rosetta.d.ts",
-      "import": "./dist/common/rosetta.js",
-      "default": "./dist/common/rosetta.js"
-    },
     "./compat/common/settingConstants": {
       "types": "./dist/common/settingConstants.d.ts",
       "import": "./dist/common/settingConstants.js",
@@ -196,11 +186,6 @@
       "import": "./dist/events/coreEvents.js",
       "default": "./dist/events/coreEvents.js"
     },
-    "./compat/hub/hub": {
-      "types": "./dist/hub/hub.d.ts",
-      "import": "./dist/hub/hub.js",
-      "default": "./dist/hub/hub.js"
-    },
     "./compat/interfaces/Confirm": {
       "types": "./dist/interfaces/Confirm.d.ts",
       "import": "./dist/interfaces/Confirm.js",
@@ -216,6 +201,11 @@
       "import": "./dist/interfaces/DatabaseRebuilder.js",
       "default": "./dist/interfaces/DatabaseRebuilder.js"
     },
+    "./compat/interfaces/FileReflectionProvenance": {
+      "types": "./dist/interfaces/FileReflectionProvenance.d.ts",
+      "import": "./dist/interfaces/FileReflectionProvenance.js",
+      "default": "./dist/interfaces/FileReflectionProvenance.js"
+    },
     "./compat/interfaces/FileHandler": {
       "types": "./dist/interfaces/FileHandler.d.ts",
       "import": "./dist/interfaces/FileHandler.js",
@@ -656,7 +646,7 @@
     "@smithy/middleware-apply-body-checksum": "^4.3.9",
     "@smithy/types": "^4.14.3",
     "@smithy/util-retry": "^4.4.5",
-    "@trystero-p2p/nostr": "^0.24.0",
+    "@trystero-p2p/nostr": "0.25.3",
     "diff-match-patch": "^1.0.5",
     "events": "^3.3.0",
     "fflate": "^0.8.2",

package/dist/common/i18n.d.ts

@@ -1,18 +0,0 @@
-import type { AllMessageKeys, I18N_LANGS } from "./rosetta.js";
-import type { TaggedType } from "./types.js";
-export declare let currentLang: I18N_LANGS;
-export declare function getResolvedLang(lang?: I18N_LANGS): I18N_LANGS;
-export declare function isAutoDisplayLanguage(lang: I18N_LANGS): boolean;
-export declare function __getMissingTranslations(): string[];
-export declare function __onMissingTranslation(callback: (key: string) => void): void;
-export declare function setLang(lang: I18N_LANGS): void;
-export declare function $t(message: string, lang?: I18N_LANGS): string;
-export declare function translateIfAvailable(message: string, lang?: I18N_LANGS): string;
-/**
- * TagFunction to Automatically translate.
- * @param strings
- * @param values
- * @returns
- */
-export declare function $f(strings: TemplateStringsArray, ...values: string[]): string;
-export declare function $msg<T extends AllMessageKeys>(key: T, params?: Record<string, string>, lang?: I18N_LANGS): TaggedType<string, T>;