Manifests and contracts

Import public contracts from app.sync_v2.sdk. All persisted or API-visible values must be JSON-safe. Ratings use Decimal normalized to 0..1; do not use binary floating-point values as canonical ratings.

Manifest fields

Field	Source	Target	Purpose
source_type / target_type	Yes	Yes	Stable lowercase provider key used by instances and discovery
label	Yes	Yes	Human-readable provider name
plugin_version	Yes	Yes	Version of that provider implementation
sdk_version	Yes	Yes	Must equal SYNC_V2_SDK_VERSION (5)
supported_media_types	Yes	Yes	Canonical media keys such as movie and show
auth_modes	Yes	Yes	none, hosted, or custom
resources	Yes	Yes	Public links such as website, API docs, or item URL template
capabilities	Yes	Yes	Stable facts used by validation and feature resolution
scopes	Yes	No	Dynamic profile selections such as libraries

Provider type, capability, action, feature, and setting keys must remain stable. Changing the meaning of a persisted feature requires incrementing its feature version. A breaking public SDK change requires a new SDK version.

Capabilities are executable promises

A capability is not a decorative badge. The registry checks selected contracts:

• changes.read requires SourceRuntime.read_changes();
• events.parse requires parse_event();
• view_history.events requires read_view_history();
• artwork.read requires fetch_artwork();
• collections.read requires scan_collections();
• custom-list target capabilities require list read/write/revert methods.

Every feature’s required capabilities must also be present in its plugin manifest. Media compatibility and source/target capabilities jointly decide whether the profile resolver exposes the feature.

Declarative configuration

ConfigSchema supports these field types:

Type	Typical use
BOOLEAN	Feature or instance option
STRING	URL, username, or non-secret text
NUMBER	Pacing, threshold, count, or numeric provider option
SECRET	API keys or client secrets; never returned after storage
SELECT	One value from declared choices
ORDERED_SELECT	Every choice exactly once in user-defined order
MULTI_SELECT	Zero or more unique declared choices

Fields may declare defaults, required state, group/order, descriptions, help text, placeholders, regex patterns, numeric range/step, and visibility for hosted or custom auth modes. The generic API and frontend render the schema; plugins cannot inject JavaScript.

Plugin and runtime contracts

SourcePlugin exposes a SourceManifest, instance schema, optional source filter features, auth, actions, and create_runtime(SourceContext). SourceRuntime must implement:

• list_scope_options();
• scan_items().

Changes, events, history, artwork, and collections are optional and capability-gated.

TargetPlugin exposes a TargetManifest, instance schema, HttpPolicy, target features, auth, actions, and create_runtime(TargetContext). TargetRuntime must implement:

• map_items() returning zero-to-many TargetMapping values per source item;
• read_items() returning current provider snapshots;
• write_items() returning one WriteOutcome per operation;
• revert_items() restoring values from opaque revert payloads.

The SDK supplies scalar helpers (map_item, read_item, write_item, and revert_item) on top of batch methods.

Features and operations

FeatureDefinition declares key, label, version, default, option schema, capabilities, media-enrichment requirements, phase, and UI group metadata. Supported phases are source_filter, sync, and collection_sync.

Target planners receive FeaturePlanContext and return deterministic TargetOperation values. Planning must not perform provider I/O. Each operation contains a deterministic ID, feature, source/target identity, action, reason, safe before/after values, conflict key, provider-owned apply/revert payloads, and an optional OperationPresentation for generic Runs UI labels and badges.

WriteOutcome.status is one of applied, skipped, failed, retryable, or ambiguous. Only confirmed results advance feature state. Use reconciliation inside the target runtime when a provider may have accepted an ambiguous write.

Authentication and actions

Auth implementations must agree exactly with manifest modes. A connected auth contract implements start, complete, status, cancel, and disconnect and declares unique credential keys. Targets may implement refresh through the optional refresh contract.

Actions are generic operator tools such as connection tests and provider search. Each ActionDefinition has a stable key, label, optional input schema, and a destructive flag. The target API tester renders and executes them without a provider-specific frontend page.

Keep secrets and provider payloads private

Put credentials only in context.credentials. Do not include tokens, request headers, opaque provider bodies, or private notes in diagnostics, operation presentation, logs, or safe before/after values.

Registry failures

Startup rejects incompatible SDK versions, duplicate provider/feature/action keys, malformed manifests or schemas, auth-mode mismatches, incomplete runtime contracts, and capability/method disagreements. Treat these failures as design feedback rather than bypassing registry validation.