mirror of
https://github.com/got-feedBack/feedBack.git
synced 2026-09-12 10:08:32 +00:00
83 lines
4.0 KiB
Markdown
83 lines
4.0 KiB
Markdown
# Contract: Jobs Migration Notes
|
|
|
|
## Migration Goal
|
|
|
|
Move plugin-specific long-running work into the shared `jobs` domain without breaking existing plugin queues, status screens, or backend routes during the transition.
|
|
|
|
## Native Provider Pattern
|
|
|
|
A migrated plugin should:
|
|
|
|
1. Declare the `jobs` domain in its manifest as a provider/requester as appropriate.
|
|
2. Register a native job provider after hydration.
|
|
3. Report supported job types, actions, availability, capacity, and recovery support.
|
|
4. Accept public jobs commands only through the jobs control plane.
|
|
5. Emit or report progress, log, completion, cancellation, failure, retryability, and recovery state through normalized provider operations.
|
|
6. Keep actual artifacts, file paths, command lines, downloads, subprocess handles, and plugin-private state inside the provider.
|
|
|
|
## Compatibility Bridge Pattern
|
|
|
|
Existing plugin queues and status screens remain allowed during migration. Core or the plugin should record a bridge hit when a legacy queue, status surface, or job-like route is used.
|
|
|
|
Recommended bridge ids:
|
|
|
|
- `jobs.legacy-plugin-queue`
|
|
- `jobs.legacy-status-screen`
|
|
- `jobs.legacy-backend-route`
|
|
- `jobs.legacy-progress-poll`
|
|
- `jobs.legacy-update-flow`
|
|
|
|
A compatibility bridge may create or update a diagnostic job summary only when it can identify a logical job without exposing private payloads. If a native provider describes the same logical job, the native provider owns the user-visible job and the compatibility record remains diagnostics-only.
|
|
|
|
## Provider Adoption Examples
|
|
|
|
### Sloppak Converter
|
|
|
|
- Job types: conversion and optional stem-prep coordination.
|
|
- Expected actions: enqueue, inspect, cancel when supported, retry when inputs are unchanged.
|
|
- Bridge sources: existing converter queue UI and backend conversion routes.
|
|
|
|
### Tab/Profile Import
|
|
|
|
- Job types: import and validation.
|
|
- Expected actions: enqueue, inspect, cancel before start, retry failed validation/import when safe.
|
|
- Bridge sources: plugin-specific import routes and status screens.
|
|
|
|
### Update Manager / Plugin Manager
|
|
|
|
- Job types: update check, download, install, rollback coordination.
|
|
- Expected actions: enqueue, inspect, cancel during safe phases, retry failed downloads.
|
|
- Extra care: plugin install/update policy and external-service trust remain outside this slice; jobs records only safe state and outcome summaries.
|
|
|
|
### Studio / Preview Work
|
|
|
|
- Job types: preview generation, render, analysis, studio processing.
|
|
- Expected actions: enqueue, inspect, cancel, pause/resume only when provider can safely preserve state.
|
|
- Extra care: recording and audio processing semantics remain outside this slice.
|
|
|
|
## Removal Gates
|
|
|
|
Legacy job bridges can be removed only when:
|
|
|
|
1. Bundled providers use native `jobs` registration for normal queue/progress/cancel/retry flows.
|
|
2. Normal conversion, import, update, preview, and studio smoke runs show no unexpected bridge hits.
|
|
3. Provider rehydration does not duplicate providers, active jobs, terminal jobs, or status listeners.
|
|
4. Privileged enqueue without explicit user approval returns denied or user-action-required before work begins.
|
|
5. Provider-selection-required is observable when multiple compatible providers lack selected/default choice.
|
|
6. Scheduling tests show user-approved interactive jobs before background/maintenance jobs and FIFO within priority.
|
|
7. Reload tests show only provider-recoverable jobs restored; other non-terminal jobs become orphaned or provider-unavailable with safe reasons.
|
|
8. Diagnostics contain no unredacted paths, tokens, command lines, raw artifacts, media data, native handles, subprocess handles, or provider-private payloads.
|
|
|
|
## Out Of Scope During Migration
|
|
|
|
The jobs domain does not define:
|
|
|
|
- media import/export file semantics
|
|
- plugin installation trust or rollback policy
|
|
- external service endpoint trust rules
|
|
- recording capture or take storage semantics
|
|
- audio-effects processing, model loading, or IR inventory
|
|
- backend route privilege review
|
|
|
|
Those domains may use jobs state later, but they should not hide their own trust and data contracts inside this slice.
|