Plugin API 3.9 reference
FolderRewind 1.9.6 supports API 3.9, while the public NuGet SDK is currently 3.6.0. Public examples retain API 3.6. New interfaces such as spatial preview require matching contracts built from the release source; SDK 3.9.0 is not available from NuGet. Assembly identity remains 3.0.0.0.
Review Plugin API 3.9 lifecycle, capabilities and Host services, distinguishing Host contracts from the public SDK 3.6.0 development surface.
Public BCL-only contracts live in FolderRewind.Plugin.Abstractions, targeting net10.0. Public package 3.6.0 represents API 3.6; the Host source contracts support API 3.9; assembly identity remains 3.0.0.0. Compatibility requires equal majors and a Host minor at least as high as the requested minor, independently of the app version.
Lifecycle and registration
IFolderRewindPlugin exposes ActivateAsync(IPluginActivationContext, CancellationToken) and DeactivateAsync(CancellationToken). Product, service and capability facts are static manifest data. The Host validates and commits the state patch in PluginActivationResult.
Activation reads settings and config/folder snapshots, and registers each instance once, recognizing all of its capability interfaces, with at most one implementation per contract. Compose internal multiplicity yourself. Registration and manifest sets must match; capabilities are unavailable before commit, and activation cannot use DataStore.
All capabilities
| Interface | Manifest capability | Responsibility |
|---|---|---|
IDiscoveryCapability | Discovery | Discovery candidates and config drafts |
IConfigReconciliationCapability | ConfigReconciliation | Revision-bound change proposals |
IFilePolicyCapability | FilePolicy | Required file policy |
IBackupScopeCapability | BackupScope | Parameterized scope and readiness |
IBackupConsistencyCapability | BackupConsistency | Disposable consistency source lease |
IFolderMetadataCapability | FolderMetadata | Live folder details |
IVersionMetadataProviderCapability | VersionMetadataProvider | Metadata from the same stable capture |
IRestoreCoordinatorCapability | RestoreCoordinator | Config-level coordination and once-only continuation |
IRestoreStagingPreparationCapability | RestoreStagingPreparation | Bounded ordinary-Restore staging proposals |
IPluginCommandCapability | PluginCommand | Commands and default hotkeys |
IKnotLinkIntegrationCapability | KnotLinkIntegration | Commands, arguments, signals and execution |
IProviderStateMigrationCapability | ProviderStateMigration | Versioned opaque provider-state migration |
IBackupArtifactTransformerCapability | BackupArtifactTransformer | Controlled immutable artifact transformation |
IBackupCompletionObserverCapability | BackupCompletionObserver | Read-only completion observation |
IRestoreMaterializerCapability | RestoreMaterializer | Materialization into an isolated workspace |
ISpatialPreviewCapability | SpatialPreview (spatialPreview) | Read-only layers, tiles, navigation and point details |
IDiscoveryDefinitionCatalog extends a Discovery implementation; IKnotLinkTargetResolver extends KnotLink integration. Neither is registered or declared as a separate capability.
Identities and snapshots
PluginId identifies the product; ConfigKindRef is OwnerId + KindId; DiscoveryProviderId identifies discovery; StateOwnerId namespaces opaque state. Equal text does not make roles interchangeable. Display names, paths and load order do not establish ownership.
ConfigRevision binds proposals. Settings use JsonElement; Provider State includes a location and schema version. Exchange snapshots, drafts, patches, requests, results and descriptors, never writable Host models.
Host services
IPluginHostServices provides Configs, Backups, Restores, History, Notifications, KnotLink, DataStore, TemporaryStorage and Logger. requestedHostServices gates the formal façade. Artifact services arrive in operation requests and also require declarations.
Plugins execute in-process with ambient user privileges. Service gating, hashes and AssemblyLoadContext are not an OS/.NET sandbox.
Cancellation, outcomes and diagnostics
Respect OperationCancellation and PluginLifetime, dispose leases/staging resources, and avoid detached work. Readiness is Ready/Degraded/Blocked. Outcomes are Success, SuccessWithWarnings, NoChanges, Canceled, Failed, Blocked, RecoveryRequired and CommittedRecoveryRequired.
CommittedRecoveryRequired means durable commit happened but subsequent recovery is incomplete. Do not automatically retry destructive work or rejoin a game. PluginDiagnostic carries Code, Severity, Capability, Owner and Arguments; log prose is not a stable interface.
Disable and settings transitions
The Host removes routing, cancels lifetime, drains operations and calls DeactivateAsync. A bounded timeout isolates the session logically and reports RequiresRestart; physical unloading may wait for restart. Enabled Intent differs from Active, and Safe Mode preserves it.
See the tutorial, settings schema and command integration.
Discovery scope in API 3.9
The positional DiscoveryRequest(UserRoots) constructor remains. The new init property IncludeKnownLocations defaults to false. Hosts may explicitly enable it for machine/preset discovery; selected roots or adding sources to an existing config remain false. Plugins add known machine locations only when allowed, rather than expanding a selected-root scan into a machine scan.
var scoped = new DiscoveryRequest(userRoots);
var automatic = new DiscoveryRequest(userRoots) { IncludeKnownLocations = true };
This is an optional property on Discovery, not a new capability declaration. Plugins using it request API 3.9; 3.x assembly identity remains 3.0.0.0. RestoreRequestOptions.RestorePreservePaths supplies one-shot ordinary-Restore preservation. Default option-bearing services return Blocked when unsupported instead of silently dropping options.
Spatial preview: API 3.9
The configuration Kind owner provides ISpatialPreviewCapability, statically declared as spatialPreview. DescribeAsync returns layers, display bounds, coordinates and optional height information. RenderAsync returns premultiplied BGRA tiles; InspectAsync returns point details. GetNavigationTargetsAsync supplies grouped navigation targets, and CloseAsync idempotently releases session resources.
SpatialPreviewTile.IsFinal defaults to true. When false, the Host keeps current pixels and requests visible unfinished tiles at intervals of at least 100ms. Optional SpatialPreviewLayer.CoordinateBounds limits legal coordinate navigation; Bounds still describes generated data. The Host freezes and validates provider output. Providers respect cancellation and do not edit saves through preview.
See the map guide.