Process & Registry

Media edition processing and catalogue ownership

This document defines the shared responsibility boundary between Amoleo FrameSync, Amoleo Editions, Plex, and Amoleo Registry.

It is the family-wide source of truth for where media files, edition knowledge, processing state and identity belong.

Core model

Amoleo Editions ⇄ FrameSync ⇄ Plex
         │
         └── Registry-backed Title / Edition identity

FrameSync is the processing workbench between the durable catalogue and the user's actual media library. It is not itself a permanent system of record.

Ownership matrix

A useful test is:

If FrameSync disappears, no durable catalogue or media-library truth should disappear with it.

Durable edition knowledge belongs in Editions. Actual owned media and Plex-facing library state belong in Plex.

FrameSync ↔ Editions

The integration is bidirectional.

Editions to FrameSync

FrameSync may retrieve catalogue knowledge to support an active job, including:

• edition/cut/release identity;
• media format and release dates;
• known technical specifications;
• presentation/mastering facts;
• provenance/review state;
• verified synchronization relationships and exact timing factors;
• later, piecewise/edit-map relationships.

Downloaded data can pre-populate and validate a job, but live media observations may still reveal differences. Conflicts must be reviewable rather than silently forcing one side to win.

FrameSync to Editions

FrameSync may publish reviewed/verified observations and calculations, including:

• stable technical edition metadata;
• cut/release/media-format facts;
• verified presentation/mastering characteristics;
• synchronization relationships, direction and exact timing factors;
• provenance identifying FrameSync method/version and verification state;
• later, piecewise/edit-map relationships.

Editions owns the durable record. FrameSync owns the calculation/inspection mechanism.

FrameSync ↔ Plex

FrameSync may use Plex as both an input and an output boundary.

Plex to FrameSync

FrameSync may:

• discover Plex movie libraries and existing editions/files;
• select an existing Plex file as processing input;
• read relevant Plex metadata/Labels;
• use Plex item/file identity to avoid duplicate imports.

FrameSync to Plex

FrameSync may:

• choose an eligible Plex library/storage root based on accessibility and free space;
• place a verified completed output into that library using canonical Plex naming;
• request/coordinate Plex discovery/refresh;
• verify the resulting Plex item/edition;
• apply/reconcile FrameSync-managed Labels such as IMAX, Native IMAX, Open Matte, or 4K DI where supported.

Plex server-local paths are not assumed to be writable from the FrameSync machine; explicit path mapping may be required.

Plex Labels describe the owned media item. Editions may contain the corresponding catalogue fact independently because Editions is the shared catalogue, not merely a mirror of one user's Plex library.

FrameSync persistence rule

The target architecture is that FrameSync stores no permanent domain catalogue.

FrameSync may use:

1. Transient processing state — in-memory or temporary local job state, working files, caches, probes, review choices and intermediate outputs. This is disposable.
2. Temporary Editions-compatible staging data — only while Amoleo Editions does not yet exist, for durable catalogue facts that will eventually be migrated into Editions.

The staging store is a transition mechanism, not a third source of truth.

It must:

• contain only data that legitimately belongs in Editions later;
• preserve raw-vs-reviewed distinction and provenance;
• be versioned/exportable/importable;
• exclude Plex file paths, storage availability and library ownership;
• exclude processing-only files/caches/output destinations;
• have a defined migration path into Editions;
• cease to be authoritative once Editions is available and migration is complete.

Existing FrameSync project/manifest persistence is therefore legacy implementation state to classify and migrate, not a permanent architectural commitment.

Failure and conflict rules

• FrameSync must not guess an unresolved Registry Edition identity.
• Editions conflicts must be surfaced for review rather than silently overwritten.
• Plex import is not successful merely because a filesystem copy succeeded; the expected Plex item/edition must be recognised.
• Existing Plex files, Labels and metadata not owned by FrameSync must not be silently overwritten.
• Plex unavailability must not corrupt media-processing results.
• Editions unavailability must not prevent local processing; before Editions exists, durable catalogue facts can use the temporary staging store.
• Once Editions exists, FrameSync should use Editions for durable catalogue reads/writes rather than growing the staging store into a permanent local database.

Related implementation work

• FrameSync #2 — synchronization relationship exchange with Editions.
• FrameSync #3 — technical edition metadata exchange with Editions.
• FrameSync #14 — Plex libraries, storage handoff and Labels.
• FrameSync #15 — processing-state boundary and migration of legacy manifests.
• FrameSync #22 — canonical Plex edition naming and structured release metadata.
• Editions #16 — shared authenticated editor/MCP application API.
• Editions #17 — bidirectional FrameSync catalogue exchange and staging migration.

Generated from docs/media-edition-ownership.md. Edit there and re-run npm run build in docs-site-src/ — never hand-edit a page.