filmopen_sync

A snapshot

This specification is a copy of docs/software/packages/filmopen_sync.md in the application’s repository, taken at commit 0b4fe88 of 11 November 2026. It is imported byte for byte and is not edited here; a change is made there, and arrives with the next snapshot.

Generated by scripts/package_digest.py; regenerate, never edit.

Keeping a film’s data/ and media/ in step with a target that shares them — a folder on a service, a folder on this computer — local first: what a target has and what it lacks is one difference, and the difference runs as sending and receiving jobs of filmopen_jobs, media four at a time and documents one at a time, through a lost connection, a closed application and a hold a sign-in or a person sets. Pure Dart; it imports the format and the jobs engine and nothing of the application, and it draws nothing: its state is JobViews.

pure Dart. 27 files, 4,219 lines under lib/; 276 tests in 29 files. Barrel: lib/filmopen_sync.dart.

Depends on

• filmopen_format — uses ProjectArea, ProjectSource, StaleFileException, Take, canonicalRootPath, documentsFolder, isDurableProjectKey, isMediaFileName, mediaFolder, projectAreaOf, projectManifestFileName, projectSourceKey
• filmopen_jobs — uses JobAction, JobActionAck, JobCheckpoint, JobEngine, JobHold, JobPersistence, JobPhase, JobReport, JobRequest, JobResult, JobRun, JobUnavailable, JobView, JobViews, refuseCredentialKeys
• filmopen_test_support (dev) — uses nothing by name the digest could see

Third-party: crypto.

Used by

filmopen_app, filmopen_cloud, filmopen_drive, filmopen_jobs_ui, filmopen_sharing, filmopen_state

Public API

What the barrel exports, file by file. A name is class, enum, mixin, extension, typedef, a top-level function, getter, setter or variable; under a class, its public constructors, fields, getters, setters and methods.

lib/src/folder_target_stub.dart

• class FolderSyncTarget — A target that is a folder on this computer.
  • FolderSyncTarget(this.root) — Retains the configured root on platforms without filesystem access.
  • final String root — The configured folder, which this platform cannot access.

lib/src/sync_environment.dart

• class SyncEnvironment — What the sync needs from the application without importing it: the open film’s source and target, and the clock.
  • bool isOpen(String projectKey) — Whether the film with [projectKey] is the open one, not closed and not loading, whatever its target.
  • SyncBinding? capture(String projectKey) — The binding of the film with [projectKey] while it is the open one and has a target.
  • DateTime now()
• class SyncBinding — The film and the target a job is bound to, in memory only.
  • SyncBinding({required this.source, required this.target})
  • final ProjectSource source
  • final SyncTarget target
  • String get projectKey — The film’s key, from its source.

lib/src/sync_lane.dart

• enum SyncLane — The two lanes of the queue: media, and the JSON documents with the manifest.
  • values: media, data
  • String get id — The lane’s name in the engine: sync:media, sync:data.
  • String get kind — The job kind the lane’s runner is registered under: sync.media, sync.document.
  • String get fetchKind — The receiving job kind registered in this lane.
  • static SyncLane? laneOf(String kind) — The lane of one of the four sync kinds, or null for unrelated work.
  • static bool isFetchKind(String kind) — Whether [kind] is one of the two receiving job kinds.
  • static bool isSyncKind(String kind) — Whether [kind] belongs to either direction of sync.

lib/src/sync_ledger.dart

• class SyncLedger — What a film and target last agreed on, with conflicts set aside at their two document hashes.
  • factory SyncLedger.inMemory() — Keeps agreements and set-aside conflicts for this application run only.
  • factory SyncLedger.inDirectory(String directory, {JobReport? report}) — Keeps hashed ledger files directly in [directory], using memory where files are unavailable.
  • Future<Map<String, String>> agreed(String projectKey, String targetId) — Returns the agreed document hashes, empty when a ledger is absent or unreadable.
  • Future<void> agree(String projectKey, String targetId, String path, String md5) — Records one agreed hash and forgets any conflict set aside for that path.
  • Future<void> agreeAll(String projectKey, String targetId, Map<String, String> byPath) — Records all agreed hashes and clears their set-aside conflicts in one write.
  • Future<void> setAside(String projectKey, String targetId, String path, { required String mine, required String theirs, }) — Sets a conflict aside only while both [mine] and [theirs] remain unchanged.
  • Future<Map<String, ({String mine, String theirs})>> asides(String projectKey, String targetId) — Returns the document conflicts set aside, each with the two hashes at dismissal.
  • Future<void> decide(String projectKey, String targetId, Future<Map<String, String>> Function(Map<String, String> agreed, Map<String, ({String mine,… — Runs a pass’s whole ledger transaction as one serialized step (§6.14).

lib/src/sync_parts.dart

• class SyncParts — Media fetch bytes held by film hash and job id until verified publication.
  • factory SyncParts.inMemory() — Keeps parts in memory for a session film or a platform without files.
  • factory SyncParts.inDirectory(String directory) — Keeps parts directly below [directory], in a separate folder for each film hash.
  • Future<int> held(String film, String id) — Returns the retained prefix length, or zero when this job holds no part.
  • Future<void> append(String film, String id, Stream<List<int>> bytes) — Appends arriving bytes and flushes the retained prefix before completing.
  • Stream<List<int>> read(String film, String id) — Reads the retained prefix from its first byte for verification or publication.
  • Future<void> discard(String film, String id) — Removes only this job’s owned part after publication or a rejected transfer.
  • Future<void> keepOnly(String film, Set<String> ids) — Sweeps known part files of [film] whose ids are absent from [ids], touching no other film.

lib/src/sync_rules.dart

• class SyncRules — The numbers of the queue, in one place, with the seams a later rule fills.
  • const SyncRules({ this.mediaAtOnce = 4, this.documentsAtOnce = 1, this.firstRetry = const Duration(seconds: 5), this.longestRetry = const Duration(…
  • final int mediaAtOnce — How many media files move at once, whatever the film.
  • final int documentsAtOnce — How many documents move at once: one, in path order, so a target sees a film change a file at a time.
  • final Duration firstRetry
  • final Duration longestRetry
  • final int attemptsBeforeAttention — After this many failed attempts a send needs a person; it is never abandoned by itself.
  • final Duration settle — How long a reconcile waits after a change before it looks, the seam buffering fills.
  • final double progressStep — The share of a file sent between two progress checkpoints, so the journal is not written per chunk.
  • Duration retryDelay(int failures, {Random? random}) — The wait before attempt failures + 1: [firstRetry] doubled per failure up to [longestRetry], with a fifth of jitter.
  • Map<String, int> get capacities — What JobEngine is constructed with: the two lanes and their ceilings.

lib/src/sync_service.dart

• typedef typedef SyncTrace — Hears one sync event and its fields: the film’s key, project-relative paths, codes, counts, stages, errors’ types and messages, and milliseconds (§6.14).
• typedef typedef SyncDeferral — Answers whether the send of the project-relative [path] in the film with [projectKey] waits for now: a document whose form is open (§6.14).
• typedef typedef MediaOnDemand — Answers whether the film with [projectKey] leaves its remote-only media in the cloud until something reads them (§6.14, media on demand).
• typedef typedef SyncHeldTexts — The documents’ text by project-relative path, as the app holds the open film for its decisions (§6.14).
• class SyncAvailability — The media files of one film that the target holds and this device does not yet (§6.14, media on demand).
  • const SyncAvailability({required this.projectKey, required this.media}) — Names the film and its available media, as project-relative paths under media/.
  • final String projectKey — The source key of the film.
  • final Set<String> media — The available files’ project-relative paths; empty once none is left or the target changed.
• class ReconcileIncomplete — A strict reconcile did not finish its pass: the target could not be listed, or a newer pass superseded it (§6.14).
  • const ReconcileIncomplete(this.stage, this.code) — Names the [stage] that stopped the pass, inventory or superseded, and its safe [code].
  • final String stage — inventory or superseded.
  • final String code — A safe code: signInNeeded while FilmOpen Cloud waits for a sign-in, a target’s own code (unreachable where the network failed, unavailable where the target is missing or not found), the failing error’s type, or…
• class SyncService — The application owns one: it lists a film and its target, queues the difference as jobs, and answers their views.
  • factory SyncService({ required JobEngine engine, required SyncEnvironment environment, SyncRules rules = const SyncRules(), SyncLedger? ledger, Syn… — Registers the four runners on [engine]; [report] hears the problems the engine’s own callback does not see.
  • static SyncService current — Starts as NoSyncService; the application installs its own.
  • Future<void> restore(String projectKey) — Binds a film’s jobs, sweeps only its durable parts, wakes its waiting work and reconciles once.
  • Future<int> reconcile(String projectKey, {String reason = 'change', bool settle = true, bool strict = false}) — Lists both sides and queues sends, fetches and conflicts.
  • Future<List<String>> localChanges(String projectKey) — The film’s documents, by project-relative path, whose content differs from what the ledger last agreed with its target, a document never agreed included: what of the folder is not yet on the target, read locally with…
  • void accountSignedIn() — The FilmOpen account reports a user: FilmOpen Cloud, which had no token, is listed again at the next pass (§6.14).
  • List<JobView> jobsFor(String projectKey) — The film’s sync jobs, whatever their lane.
  • JobViews get views — Publishes the service’s sync job snapshots.
  • Stream<SyncArrival> get arrivals — Broadcasts each file placed in a film once per successful publication, closing with the service.
  • Stream<SyncAvailability> get availability — Each film’s available media, the current value of every film replayed to a new listener first (§6.14).
  • Set<String> availableIn(String projectKey) — The film’s available media now, as project-relative paths: the snapshot [availability] replays, read at once.
  • Future<String?> fetchNow(String projectKey, String path, {String reason = 'read'}) — Fetches one available media file now, in the film’s decision order: answers the fetch job’s id — an existing request for [path] joined rather than doubled — or null where [path] is not available (§6.14).
  • Future<JobActionAck> act(String id, JobAction action) — Applies an action, recording accepted conflict dismissals and an accepted sign-in before answering.
  • SyncStatus? statusOf(String projectKey) — Every file of the film against its cloud copy: the last pass’s comparison, the film’s jobs laid over it; null where no pass has compared it, or its target is gone or changed since (§6.14).
  • Stream<String> get statusChanges — The key of each film whose comparison was made or cleared, at once; its jobs’ changes are [views]’ (§6.14).
  • Future<void> close({Duration grace = const Duration(seconds: 10)}) — Stops scheduling and drains the owned engine within [grace].
• class NoSyncService — The service that syncs nothing: the web, a build with no application files, a test without one.
  • const NoSyncService() — Supplies inert sync behavior without starting any listener or storage.
• class SyncArrival — A verified file placed in the named film, for one publication per arrival burst.
  • const SyncArrival({required this.projectKey, required this.path, this.text}) — Names the film and the project-relative file that was published, and a document’s text as it reads.
  • final String projectKey — The source key of the film receiving the file.
  • final String path — The project-relative file path, without a machine or target address.
  • final String? text — A document’s text as a reader of the written file decodes it; null for a medium.

lib/src/sync_status.dart

• enum SyncFileState — Where one file of a film stands against its cloud copy (§6.14).
  • values: same, toSend, toFetch, conflict, available, moving, waiting, problem
• class SyncFile — One file of a film and its [state].
  • const SyncFile({required this.path, required this.state, this.progress, this.code}) — A file at [path] in [state]; [progress] where a transfer measures it, [code] for a waiting or failed one.
  • final String path — The project-relative path.
  • final SyncFileState state — Where the file stands.
  • final double? progress — A moving file’s measured progress, 0–1.
  • final String? code — A waiting or failed transfer’s job code.
• class SyncStatus — Every file of a film against its cloud copy, as the last comparison found them, its transfers since laid over.
  • SyncStatus({required this.projectKey, required this.at, required List<SyncFile> files, Set<String> doneBefore = const {}}) — The status of [projectKey] compared [at], one entry per file in path order; [doneBefore] names the jobs already finished when it was compared, whose end the comparison already knows.
  • factory SyncStatus.decided(String projectKey, DateTime at, LocalInventory local, TargetInventory target, SyncDifference difference, {Set<String> do… — The status a pass decided: every path of [local] and [target] that syncs, in [difference]’s word; a document whose two copies differ and that no list names — a conflict set aside — still [SyncFileState.conflict]; else…
  • final String projectKey — The film’s key.
  • final DateTime at — When the comparison was made.
  • final List<SyncFile> files — The files, in path order.
  • final Set<String> doneBefore — The ids of the jobs finished when the comparison was made.
  • Map<SyncFileState, int> get counts — How many files are in each state, the states with none left out.
  • SyncStatus withJobs(List<JobView> jobs) — This status with [jobs] laid over it: a file being sent or fetched is [SyncFileState.moving], a waiting one [SyncFileState.waiting], a conflict asking the person [SyncFileState.conflict] and any other failed one [Sync…
  • SyncStatus settledBy(JobView job) — This status with [job]’s finished result kept, as [withJobs] would show it, for once the job is gone; this status itself where [job] is not a finished transfer laid over it.
• function String? syncPathOf(String? placeKey) — The project-relative path a sync job’s place key names, or null where it is no sync job’s (§6.14).

lib/src/sync_target.dart

• class SyncTarget — A place a film’s documents and media are kept in step with, reading files as well as receiving them.
  • String get identity — An opaque, stable name of this target for the journal.
  • String get kind — A short word a payload records for the target that took a job: folder, drive.
  • Future<TargetInventory> inventory() — Every file the target holds under data/ and media/ and the manifest at its root, with its size and, for a document always and for media where the target knows it, its MD5.
  • Future<TargetEntry?> find(String path) — One file’s entry, or null: how a send whose answer was lost is settled before a byte is sent again.
  • Future<SyncBytes> fetch(String path, {int from = 0}) — Streams [path] from [from], or from zero when seeking is unavailable, with the whole file’s measurements.
  • Future<int> committed(Map<String, Object?> checkpoint) — How many bytes of a send a previous attempt already placed, by the checkpoint that attempt reported; 0 where the target cannot resume.
  • Future<SyncReceipt> put(String path, Stream<List<int>> bytes, { required int length, required int from, required bool replace, String? md5, Map<Str… — Places [bytes], which start at byte [from] of a file [length] long, under [path].
• class TargetEntry — What a target holds under one path.
  • const TargetEntry({required this.path, required this.size, this.md5}) — Describes a file without retaining any of its bytes.
  • final String path — The file’s project-relative path.
  • final int size — The whole file’s length in bytes.
  • final String? md5 — The whole file’s MD5, required for documents by the target contract.
• class TargetInventory — Every file a target holds, by path.
  • const TargetInventory(this.entries) — Wraps the target’s entries indexed by project-relative path.
  • final Map<String, TargetEntry> entries — Every retained target file, indexed by its path.
• class SyncBytes — A target file’s byte stream and the measurements of the whole file.
  • const SyncBytes({required this.from, required this.length, this.md5, required this.bytes}) — Describes a stream beginning at [from], possibly zero when a target ignores a requested offset.
  • final int from — The first byte’s offset in the whole file.
  • final int length — The whole file’s byte length, including any prefix omitted from this stream.
  • final String? md5 — The whole file’s MD5 where the target knows it.
  • final Stream<List<int>> bytes — The bytes from [from], whose subscription the consumer owns and cancels.
• class SyncReceipt — A target’s confirmation of a send.
  • const SyncReceipt({required this.path, required this.size, this.md5}) — Confirms the complete file published by a send.
  • final String path — The published file’s project-relative path.
  • final int size — The published file’s whole byte length.
  • final String? md5 — The published file’s MD5 where the target knows it.
• enum SyncFailure — What a target’s failure is worth: trying again by itself, a person signing in, or nothing.
  • values: retry, signIn, never
• class SyncTargetException — A target’s failure as a stable code and its verdict, carrying its cause’s words into every '$error' that logs it.
  • const SyncTargetException(this.code, this.failure, {this.cause}) — Carries a stable code, its retry or attention policy and, where a target has one, the cause’s words.
  • final String code — The failure’s code, which a job’s state carries.
  • final SyncFailure failure — Whether an attempt can retry, needs sign-in, or cannot succeed.
  • final String? cause — The underlying failure’s words, for the log.

lib/src/transfer_streams.dart

• function Stream<Uint8List> transferChunks(Stream<List<int>> source, int size, int expected) — Cuts [source] into parts of [size] bytes, the last shorter, refusing a stream whose length is not [expected].
• function Stream<List<int>> ownedTransfer(Stream<List<int>> bytes, { required Duration timeout, required Object? Function(String outcome, Object? cause, int… — Owns a received stream’s subscription, paused until a consumer listens, through EOF, failure, cancellation or abandonment after [timeout] without a listener.

Internal

Files under lib/ the barrel does not reach; nothing outside the package may import them.

• lib/src/difference.dart: PendingTransfer, PendingFetch, AvailableMedia, SyncConflict, SyncDifference, _pathOrder
• lib/src/folder_target_io.dart: FolderSyncTarget, _checkStaging, _publisher, _NativePublisher
• lib/src/ledger_store.dart: LedgerStore, MemoryLedgerStore
• lib/src/ledger_store_io.dart: createLedgerStore, _DirectoryLedgerStore
• lib/src/ledger_store_stub.dart: createLedgerStore
• lib/src/local_bytes.dart
• lib/src/local_bytes_io.dart: openLocalBytes
• lib/src/local_bytes_stub.dart: openLocalBytes
• lib/src/local_inventory.dart: LocalEntry, LocalInventory
• lib/src/md5_of.dart: md5Of
• lib/src/sync_parts_io.dart: createSyncParts, _DirectoryParts
• lib/src/sync_parts_stub.dart: createSyncParts
• lib/src/sync_payload.dart: checkSyncPayload, isSyncPath, safeSyncCode