obsidian-livesync/docs/glossary.md

date, commonlib-version, self-hosted-livesync-version, status

date	commonlib-version	self-hosted-livesync-version	status
2026-09-03	0.1.21	1.0.24	accepted

Project glossary

This glossary records stable, project-specific meanings used by Self-hosted LiveSync. Ordinary English and established technology terms retain their usual meanings unless they are defined here. Exact code identifiers, API names, and user-interface labels retain their source spelling.

The sections describe the intended audience, not a visibility guarantee. A term in the developer and design section can appear in code, tests, logs, or diagnostics. That does not make it user-interface vocabulary or a public extension contract.

User-facing and operational terms

These terms can appear in the user interface, user documentation, setup and recovery guidance, or diagnostics intended for users.

A–R

• Boot-up sequence (boot sequence): The initialisation process of the plug-in when Obsidian starts. It begins with loading the plug-in, setting up core services, loading saved settings, and opening the local database. After the layout is ready, the plug-in checks for flag files, runs configuration diagnostics, connects to the remote database, and begins file watching. The sequence finishes when the plug-in is ready and operational.
• Broken files (size mismatch): A state where a file's Metadata and the content stored in its Chunks do not match, causing file retrieval or synchronisation failures. Inspect these mismatches with Inspect conflicts and file/database differences in the Hatch pane, then handle one exact revision at a time.
• Chunk / Chunks: Divided units of data stored in the database or Object Storage to support efficient synchronisation.
• Compaction: A database maintenance procedure which discards old historical document revisions to reduce remote database size.
• Continuous replication: A provider's long-running replication mode. It remains active to exchange changes until stopped and is distinct from a finite OneShot Sync operation.
• Custom HTTP Handler / Use Internal API (CORS bypass settings): Settings which bypass CORS restrictions by routing requests through Obsidian's native request APIs. There are separate settings for each central remote type:
  • S3-compatible Object Storage (useCustomRequestHandler): Labelled Use Custom HTTP Handler in the standard settings tab and Use internal API in the Svelte Setup Wizard dialogue. It is represented as useProxy in Setup URI query parameters for compatibility.
  • CouchDB (useRequestAPI): Labelled Use Request API to avoid inevitable CORS problem in the standard settings tab and Use Internal API in the Svelte Setup Wizard dialogue. It is represented as useRequestAPI in Setup URI query parameters.
• Customisation Sync: The feature which synchronises settings, snippets, themes, and plug-ins. Write 'Customisation' with an 's' in documentation; technical configuration and links can use customization where required.
• Database Adapter (IDB and IndexedDB): The local database storage interface used by PouchDB. The IDB adapter is recommended because the older IndexedDB adapter is obsolete and can cause memory leaks in LiveSync mode. Switching adapters requires local data migration and an Obsidian restart, but not a full database rebuild.
• Database Suffix (additionalSuffixOfDatabaseName): A suffix appended to the database name so that multiple Vaults with the same name can synchronise to the same remote server.
• E2EE Algorithm: The cryptographic algorithm version used for end-to-end encryption. All synchronising devices must use a compatible version, such as V2 or V1.
• Eden (Eden Chunks): A sunset-compatibility optimisation in which newly created Chunks are held inside the document until they stabilise, before becoming independent Chunks.
• Fast Setup (Simple Fetch): The preferred automated initial synchronisation flow for a secondary device. It uses Streaming replication for the initial download and delays local file reflection to avoid temporary synchronisation warnings.
• Fast Fetch: The CouchDB-specific Streaming replication path used by Fast Setup. It reads the changes feed in bounded pages and persists a checkpoint so an interrupted transfer can resume. An ineligible transport uses the ordinary fetch path instead.
• Flag files (redflag.md, redflag2.md, and redflag3.md): Special Markdown files or directories at the Vault root which stop the boot-up sequence or trigger recovery work. redflag.md suspends all processes, redflag2.md (flag_rebuild.md) triggers a full database rebuild, and redflag3.md (flag_fetch.md) discards and fetches the local database again.
• Garbage Collection (GC): The maintenance process which identifies Chunk documents not reachable from a current file or conflict branch, records logical deletions for them, propagates those deletions, and requests remote compaction to reclaim storage.
• Hatch (Hatch pane): The troubleshooting and maintenance section in the plug-in settings. It contains diagnostics, database reset controls, status reports, and advanced edge-case settings.
• Hidden File Sync: The feature which synchronises files in hidden directories, such as .obsidian.
• JWT Authentication: An experimental CouchDB authentication option which uses a JSON Web Token instead of standard credentials. It requires a private key or secret, algorithm, expiry duration, subject, and key ID.
• LiveSync: This name has two established meanings: the shortened plug-in name for Self-hosted LiveSync, and the Sync Mode for continuous, real-time synchronisation. Prefer 'Continuous replication' in design documentation when the mode, rather than the product, is meant.
• livesync-serverpeer / WebPeer: Specialised clients which assist WebRTC peer-to-peer communication.
• Metadata (file metadata): A database document which stores file properties, including its name, path, size, modification time, and references to the Chunks containing its content. PouchDB or CouchDB revision metadata carries conflict state; the file Metadata document has no separate history field. Metadata and file content are stored separately.
• OneShot Sync (OneShot replication): One finite bidirectional synchronisation operation, normally pull then push, which is requested directly or by an event. It is distinct from Continuous replication.
• Overwrite Server Data with This Device's Files: A maintenance operation, formerly named Rebuild everything, which discards the remote database and rebuilds the local and remote databases from the current files on one authoritative device.
• Path Obfuscation: A privacy option which encrypts file paths and folder names on the remote server.
• plug-in: The spelling used in user-facing messages and general prose. Retain plugin in code, configuration, and established technical names.
• Remediation (maxMTimeForReflectEvents): A recovery setting which limits reflection of changes from the database to the Vault by ignoring file events after a specified date and time.
• Reset Synchronisation on This Device: A maintenance operation, formerly named Fetch everything, which discards the local database and rebuilds it from the remote database.

Revision

A revision is a version of one PouchDB or CouchDB document. Concurrent changes can form a revision tree with more than one current branch.

Revision modifiers describe independent properties. More than one can apply to the same revision:

• leaf: Has no known child revision.
• winner: Is the leaf selected by PouchDB or CouchDB as the current document.
• conflict: Is another current leaf which was not selected as the winner.
• Vault-matching: Represents the same file content, or the same absent-file state, as the current Vault. More than one revision can match.
• displayed: Is recorded by valid device-local file provenance as the branch represented in the Vault. A pending local edit might no longer match its bytes, but still extends this recorded branch.
• logically deleted: Represents absence of the file through a deletion marker. A logically deleted revision can also be a leaf, winner, conflict, or Vault-matching revision. An absent file retains no displayed provenance.

Avoid 'live revision' because it can mean either a current leaf or a non-deleted revision. See Independent revision properties for the relationship between revision-tree roles, Vault state, and device-local provenance.

S–Z

• Scram (Scram Switches): Emergency controls which suspend file watching or database reflection to reduce the risk of corruption or unintended changes.
• Security Seed: The remote PBKDF2 salt used to derive the encryption key for replication. It must be read from, or established on, the remote before encrypted synchronisation.
• Segmenter (Segmented-splitter): A chunking method which divides files at semantic boundaries, such as paragraphs or sections, rather than arbitrary byte boundaries.
• Self-hosted LiveSync: The name of this plug-in. 'Self-hosted' is one hyphenated word.
• Setting Doctor (Config Doctor): A diagnostic utility which identifies configuration mismatches or suboptimal settings and presents recommended values and reasons.
• Setup URI: An encrypted representation of plug-in settings and remote configuration which can be transferred to another device and opened with a passphrase.
• Signalling relay (P2P): A Nostr-compatible WebSocket relay used for peer discovery and WebRTC connection negotiation. It does not store or transfer Vault content. The project author operates a public relay as a best-effort convenience, and users can supply another compatible relay.
• Streaming replication (stream-based replication): A transfer method which downloads database documents as a continuous stream of events. Fast Setup uses it to retrieve remote Metadata efficiently.
• Sync Mode: The trigger mechanism for synchronisation. Current modes are LiveSync, for continuous replication, Periodic Sync, for work at a configured interval, and On Events, for configured application events.
• Synchronising devices: Devices which participate in the same synchronisation for a Vault. The term describes membership rather than current activity, so it includes offline and idle devices.
• TURN Server (WebRTC P2P): A Traversal Using Relays around NAT server used as an optional fallback when NAT or firewall rules prevent a direct WebRTC connection. It relays encrypted WebRTC traffic and is distinct from the signalling relay.
• Update Thinning (Batch database update): An optimisation which groups local file edits over a short delay before committing them to the local database, reducing database writes.
• WebRTC P2P (peer-to-peer): A synchronisation method which allows devices to communicate directly without a central remote database.

Developer and design terms

These definitions are stable vocabulary for architecture documents, ADRs, implementation, tests, and code review. They might never appear in the user interface. Inclusion here fixes their project meaning; it does not make the named surface a public API or extension point.

Active publication

The atomic publication of one Replicator provider, its ReplicatorInstance, and its configuration identity, owned by Commonlib's ReplicatorService. Its object identity is the admission fence for operations. An active publication is also called the active Replicator publication, and its instance is the active Replicator. 'Active publication' is more precise than 'current Replicator' when admission or retirement matters.

Adjunct P2P transport

P2P operating as an additional transport while CouchDB or Object Storage is the selected main remote. It retains its own service and room-session ownership; it is not the active Replicator for the main remote. Architecture documents can shorten this to 'adjunct P2P' where the distinction is already clear.

Admission and reservation

Admission is permission for an operation to use one exact active publication or P2P room session. A reservation records admitted work and keeps its owner alive until that work settles. Retirement closes admission before it waits for existing reservations, so later work cannot enter the retiring generation.

Bounded remote activity

A finite logical operation which can involve remote work, waiting, queueing, or local result handling. Its lifetime is broader than an individual network request. Continuous replication is not bounded remote activity. See the Bounded Remote Activity ADR.

Capability

A typed declaration that a Replicator provider supports an operation or remote resource, does not implement it, or considers it inapplicable. Capability support is explicit; callers do not infer it from a legacy method, a Boolean default, or a neutral return value.

Central remote

A CouchDB or Object Storage remote which can require central preparation and administration before replication. P2P is not a central remote. The main remote is the RemoteType selected for the active Replicator; P2P can also operate as an additional transport when a central remote is selected.

Configuration identity

An opaque projection of the effective settings which determine whether an existing provider instance or P2P binding can be retained. It can contain credentials. Code can compare an identity for equality, but must not inspect, log, persist, or display it.

Fence, generation, and epoch

A fence prevents stale work or work admitted by one owner from affecting a replacement owner or state. A generation normally changes when one local lifecycle is invalidated. An epoch identifies one session or data history where the owning contract uses that term. These values belong to distinct state machines and are not interchangeable or evidence that another owner is current.

Focused view

A narrow interface exposing only the operations required by a consumer. It delegates to a stable owner and does not independently own the underlying mutable state or resource.

Interaction authority

The explicit upper bound on user interaction permitted during an operation. User-initiated work can receive selected permissions; unattended work carries NO_INTERACTION and cannot open a dialogue, request peer selection, or obtain authority through a fallback path.

Journal remote epoch

The protocolVersion:pbkdf2salt value stored as CheckPointInfo.journalEpoch. It identifies Journal checkpoint and deduplication-cache history. It is data-history state, not a cancellation, Replicator retirement, or operation-admission fence.

Non-owning adapter

An adapter which implements a contract by delegating to another component without owning the delegated resource. Closing it releases only resources which the adapter itself owns. In particular, closing the active P2P adapter does not close the stable P2P service or its room session.

Owner and ownership

The owner is the single component responsible for creating, replacing, stopping, and disposing a resource or stateful lifecycle. A borrower, adapter, or focused view can use that resource only within its declared boundary and must not perform the owner's lifecycle operations.

P2P service, room session, and demand

The P2P service is the stable Commonlib owner which supplies focused views and owns replaceable room sessions. A P2P room session is one active room membership and the resources whose validity depends on it. Demand is one persistent or finite reason for the owner to retain a room. Releasing one demand does not close a room retained by another. A room's effective binding includes the settings, local database object, and device identity which make that session valid. A session epoch is the internal identity and fence of one room-session object, not a persisted room name or a public numeric counter. An automation baseline records peers for which the initial transfer completed in the current logical automation lifecycle; it is owned independently of a replaceable room session. A configured target is a persisted peer name selected for unattended P2P_SyncOnReplication; the request can wait for its advertisement, but cannot prompt for peer selection.

Publication retirement

The lifecycle transition which removes an active publication from current admission, asks its provider to stop transfer work, drains reservations for that exact publication, closes the old instance, and marks retirement complete. Quiescing is the state after admission has closed and before retirement completes. A replacement cannot be published across an incomplete retirement fence. A candidate is a newly constructed instance which remains private until initialisation and freshness checks permit atomic publication.

Remote resource and probe

A remote resource is a provider-declared, caller-owned object created from one effective-settings snapshot for a bounded task. A probe is a bounded, flow-specific validation or observation for connection, compatibility, setup, or diagnostics. It can use an owned remote resource or an owner-arbitrated P2P trial. It does not publish or replace the active Replicator, and the caller disposes every resource which it owns.

Replicator

The project abstraction which performs replication for one configured remote kind and implements the ReplicatorInstance lifecycle contract. Use 'replication' for the process and 'Replicator' for this runtime abstraction. A Replicator can be an owning transport implementation or a non-owning adapter; the provider contract determines the boundary.

Replicator provider definition

The exhaustive, host-composed declaration for one RemoteType: its configuration identity, Replicator factory, readiness requirement, capabilities, remote-resource factories, operation runners, and optional central administration. The readiness requirement declares which layer must establish operation preconditions. The provider catalogue is closed composition, not a runtime registry: adding a provider requires changing, shipping, and testing the owning composition. A built-in provider is one included in that shipped catalogue. Architecture prose can shorten 'Replicator provider definition' to 'provider'; it does not mean only the transport instance.

Replication outcome

The typed settlement of an attempted replication operation, represented by ReplicationOutcome. Completed, partial, blocked, cancelled, and failed states remain explicit; undefined, an empty value, or a compatibility default is not treated as successful work.

Service composition terms

• A Service Hub is the long-lived registry of service contracts for one application composition.
• A Service owns a stable shared capability and its lifecycle.
• A ServiceModule is a host-created, long-lived stateful or resource-owning capability shared through the typed ServiceModules record.
• A serviceFeature is a typed composition function which accepts declared Services and ServiceModules, registers host integration, and can return a focused view. It is not a runtime registry entry.
• A legacy Module is an existing application structure retained for compatibility. New behaviour does not acquire the complete core merely to imitate that locator pattern.

See Service feature and legacy Module boundaries for the selection and composition rules.

Suspension

A reversible lifecycle action which stops active transfer work without retiring the active Replicator publication. The P2P service also closes its current room session during application suspension because that session has a separate owner and lifecycle. Resumption can retain the Replicator instance and open a new P2P room as required.