filmopen_exchange

A snapshot

This specification is a copy of docs/software/packages/filmopen_exchange.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.

Pure Dart vocabulary for exchanging FilmOpen content: ids, field paths, projections and the $ key codec. The public API is exported through filmopen_exchange.dart.

pure Dart. 16 files, 2,711 lines under lib/; 256 tests in 25 files. Barrel: lib/filmopen_exchange.dart.

Depends on

• filmopen_format — uses AllocationInventory, Author, Catalogue, ChildEntry, ChildProblem, Entity, EntityGroup, EntityType, EpochDeclaration, FileNameParser, FilmProject, MediaEntry, Pick, PickReason, ShapeLibrary, ShapeProblemCode, ShortName, StaleFileException, VersionStem, ageFromBirthDate, blockNumber, canonicalJson, castOf, childTypes, copyDocument, cueGroupsByOwner, declaredEpochs, deepCopy, encodeEpochs, encodeNextEpoch and 18 more
• filmopen_store — uses AppLog, EntityExistsException, Guards, IdentityChangedException, InvalidContentException, NextEpochLoweredException, NoViewerException, NotYourFileException, ProjectReadOnlyException, ProjectWriter, validateContent
• filmopen_test_support (dev) — uses nothing by name the digest could see

Third-party: crypto.

Used by

filmopen_app, filmopen_assistant_ui, filmopen_browser, filmopen_forms, filmopen_plugin_host, 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/apply.dart

• class ImportResult — The ordered stage outcomes of the writable changes in one apply.
  • ImportResult(Map<ExchangeId,StageOutcome> outcomes) — Snapshots outcomes in plan order, omitting skipped nothing and refused changes.
  • final Map<ExchangeId,StageOutcome> outcomes — Each attempted or already completed writable change and its retained stages.
• function Future<ImportResult> applyPlan(ImportPlan plan, ImportWriter writer) — Applies independent changes serially, carrying stages and continuing past a failed file.

lib/src/assembler.dart

• class ExportDocument — An assembled exchange document and the problems reported while building it.
  • final Map<String, Object?> json — The envelope and detached projected content in wire order.
  • final List<ExchangeProblem> problems — The context problems followed by assembly problems, without identical duplicates.
  • final int skippedDeleted — How many selected or listed entities were left out because the version in use is deleted (§7), each once.
  • String get text — The two-space JSON wire representation, terminated by one newline.
  • int get bytes — The UTF-8 length of the wire representation.
• function String sourceHash(Projection projection, Map<String, dynamic> content, EntityType type) — Hashes the selected content before dollar escaping and exchange metadata.
• variable const exchangeCollections — The fixed type-to-collection placement shared by export and import.
• function ExportDocument assemble(ExchangeContext ctx, ScopeSelection selection, {required Scope scope, DateTime? now, bool lean = false, Map<String, Entity>… — Places selected picks in fixed body order and builds the deterministic export envelope.

lib/src/codec.dart

• class DecodedFileObject — A file object’s exchange keys and decoded content in separate owned maps.
  • final Map<String, dynamic> exchange — The root exchange keys, including unknown keys, with their values unchanged.
  • final Map<String, dynamic> content — The content with exactly one leading dollar removed from escaped keys.
• function Map<String, dynamic> escapeContent(Map<String, dynamic> content) — Copies content, adding one dollar to every dollar-prefixed key at any depth.
• function DecodedFileObject readFileObject(Map<String, dynamic> file) — Extracts root exchange keys before unescaping the remaining content at every depth.

lib/src/exchange_id.dart

• enum ExchangeKind — The three identities carried by an exchange document.
  • values: entity, batch, manifest
• class ExchangeId — An exchange identity independent of an entity’s author and version.
  • const ExchangeId(EntityType this.type, this.tag, [this.epoch]) — Names a versioned entity, or its group when a library epoch is omitted.
  • const ExchangeId.batch(String id, Author this.author) — Names the batch receipt whose identity includes its author.
  • const ExchangeId.manifest() — Names the manifest, which has no entity type, author or epoch.
  • final EntityType? type — The format type, null only for the manifest.
  • final String tag — The entity tag, batch id, or literal manifest.
  • final String? epoch — The library entity’s epoch, null for a group or a type without that axis.
  • final Author? author — The batch author, null for every other kind.
  • ExchangeKind get kind — Whether this identity names an entity, a batch or the manifest.
  • String get text — The wire identity, with no author or version on a versioned entity.
  • bool get isGroup — Whether this id spans every epoch of one library entity.
  • static ExchangeId? parse(String text) — Reads a validated group, versions key, full stem, batch stem or manifest.
  • static ExchangeId of(VersionStem stem) — Takes a parsed version’s identity, dropping its author and version.

lib/src/export.dart

• function Map<String, Object?> exportEntityDocument(Entity entity, {bool lean = false}) — The exchange object of [entity] alone: its identity and whole projected, escaped content.
• function ExportDocument exportScope(FilmProject project, Author? viewer, {required String scope, Object? arg, DateTime? now, bool lean = false}) — Exports a registered scope from the project version in use for this viewer.

lib/src/field_path.dart

• class FieldPathSegment — One key and its optional list traversal or literal entry filter.
  • final String key — The object key reached by this segment.
  • final bool isList — Whether brackets select entries of the list at this key.
  • final String? matchKey — The entry key compared with the literal, null for an unfiltered segment.
  • final String? matchValue — The exact literal value, null for an unfiltered segment.
• class FieldPath — A dotted content path with keys, list traversal and literal entry filters.
  • FieldPath(String text) — Parses the path or throws FormatException for text outside the grammar.
  • final List<FieldPathSegment> segments — The immutable segments in traversal order.
  • static FieldPath? tryParse(String text) — Reads a path without throwing on a malformed document directive.

lib/src/import_reader.dart

• class ImportNote — Information about content skipped or retained during an import.
  • const ImportNote(this.kind, {this.path, this.detail}) — Records a note kind and its optional JSON path and payload.
  • final String kind — The additive information code.
  • final String? path — The affected document or field path, where applicable.
  • final Object? detail — Structured JSON detail for the note, where applicable.
  • Map<String, Object?> get json — Serializes information without absent optional fields.
• class ImportProblem — A refusal diagnostic for a document or an individual patch.
  • const ImportProblem(this.code, {this.path, this.detail}) — Records a refusal code and its optional JSON path and payload.
  • final String code — The additive refusal code.
  • final String? path — The affected document or field path, where applicable.
  • final Object? detail — Structured JSON detail for the refusal, where applicable.
  • Map<String, Object?> get json — Serializes a refusal without absent optional fields.
• class ImportPatch — One decoded file patch with its versionless identity and source hint.
  • final ExchangeId id — The normalized identity whose current pick the planner will resolve.
  • final DecodedFileObject file — Owned exchange metadata and unescaped content, kept apart.
  • final String path — The file object’s JSON path in the received document.
  • final String? stem — The explicit stem hint, or the original full-stem id when no hint was supplied.
  • final ImportProblem? problem — The patch’s reader refusal, leaving unrelated patches usable.
• class ImportDocument — The file patches and diagnostics read without resolving or writing anything.
  • final List<ImportPatch> patches — File patches in document order, including independently refused patches.
  • final List<ImportNote> notes — Information about skipped collections, elements and group keys.
  • final List<ImportProblem> problems — Diagnostics, including duplicates which do not refuse the whole document.
  • bool get refused — Whether one of the three whole-document refusals ended reading.
• function ImportProblem? checkImportDirectives(DecodedFileObject file) — Checks directive shapes and grammatical paths without throwing on model text.
• function ImportDocument readImport(Object? document, {required String projectTag}) — Reads exchange version 1 into independent patches, refusing only three states whole.

lib/src/import_writer.dart

• class StageOutcome — The completed stages and bounded refusal of one import write.
  • StageOutcome({Map<ImportStage,String?> done = const {}, this.problem}) — Snapshots successful stages even when a later stage failed.
  • factory StageOutcome.failed(Object error, ImportStage stage, {Map<ImportStage,String?> done = const {}}) — Maps store failures to codes, carrying only the failed stage, never exception text.
  • final Map<ImportStage,String?> done — Successfully completed stages and the stems they made.
  • final ImportProblem? problem — The first failed stage’s diagnostic, absent when the requested work completed.
• class ImportWriter — The four guarded write roads available to an import apply.
  • Future<StageOutcome> update(ImportChange change) — Writes an existing pick with its reviewed expected text, completing content alone.
  • Future<StageOutcome> fork(ImportChange change) — Writes the patched fork once, then verifies that its stem is in use.
  • Future<StageOutcome> create(ImportChange change) — Makes an unlisted entity and completes or resumes its content and pick stages.
  • Future<StageOutcome> pickOnly(ImportChange change) — Compares the retained artifact before picking it, without writing its content again.
• function bool artifactMatches(Map<String,dynamic> retained, Map<String,dynamic> reviewedAfter, EntityType type, {Author? viewer, String? sourceOwner}) — Compares a retained artifact with the reviewed content under the writer’s fork rules.
• class ProjectWriterImport — Applies reviewed imports through the store as one captured importing viewer.
  • ProjectWriterImport(FilmProject project, this.reload, {required this.viewer, this.guards = Guards.enforce}) — Uses the plan’s viewer and guards for every write and every reloaded pick check.
  • final Future<FilmProject> Function() reload — Re-reads the same source and library after writes and before artifact recovery.
  • final Author? viewer — The importing viewer, fixed for this writer’s lifetime.
  • final Guards guards — The same development-mode policy used for the dry plan.

lib/src/patch_document.dart

• class PatchResult — A detached document and the changes or refusal of one pure patch.
  • final Map<String,dynamic> after — The complete resulting document, or a copy of the original on refusal.
  • final List<String> paths — Canonical field paths whose values changed, including an allocator counter.
  • final List<String> removed — Canonical field paths explicitly removed.
  • final List<ImportNote> notes — Information about ignored keys and absent removals.
  • final ImportProblem? problem — The whole-patch refusal, null when the patch was accepted.
• function PatchResult patchDocument(Map<String,dynamic> before, DecodedFileObject patch, EntityType type) — Applies replace, leaf merge and explicit removal without mutating either input.

lib/src/pattern.dart

• variable const Map<String, Set<EntityType>> patternTokens — The selector tokens a pattern may use, and for each the entity types its this-family token needs (empty: none).
• class PatternRefused — A pattern the exchange refuses to build: a fixed code and the token, both safe to log.
  • const PatternRefused(this.code, this.token) — Names the refusal; [token] is a token of [patternTokens] or the fixed word unknown.
  • final String code — unknown_token, no_entity or wrong_entity.
  • final String token — The refused token, never a key the table does not hold.
• function Scope patternScope(Map<String, Projection> lines, {required ExchangeId? entity}) — A scope built from an assistant pattern: one line per selector token, each with its projection.

lib/src/picked_script.dart

• class ExchangeProblem — A reported exchange problem with its identity and structured detail.
  • const ExchangeProblem(this.id, this.problem, [this.detail]) — Records a code without guessing at an unresolved file.
  • final String id — The identity or unreadable reference the problem concerns.
  • final String problem — The wire problem code.
  • final Object? detail — The code’s payload, such as owners, stems or a reference path.
  • Map<String, Object?> get json — Serializes the problem in the document’s fixed key order.
• class PickedOccurrence — One listing in the picked script, including pins and flagged occurrences.
  • final String id — The short stem, or the original text of an unreadable entry.
  • final Entity? entity — The version in use, independent of the entry’s pin.
  • final String? pinned — The full stem the entry pins, if any.
  • final bool duplicate — Whether this short stem already occurred, including cycles.
  • final String? problem — The flag of an unreadable or unresolved entry.
  • final bool deleted — Whether the version in use is in the recycle bin (Project Specification §7): still walked, never written.
  • final List<PickedOccurrence> children — The picked folder’s children, empty for flagged or repeated entries.
  • Map<String, Object?> get json — Writes occurrences in walk order, omitting children on flagged entries.
  • Iterable<Map<String, Object?>> get output — What this occurrence writes into its list: itself, or, deleted, nothing of its own and what it holds in its place.
• class PickedScript — The script walked through picks, with unreached folders and scenes beside it.
  • final List<PickedOccurrence> tree — The project’s listings, retaining duplicate occurrences and pins.
  • final List<ExchangeId> unfiled — Every folder and scene no picked list reaches, in type and natural tag order.
  • final List<ExchangeProblem> problems — Flags and differing pins encountered in the walk.
  • final Set<String> deleted — The short stems met whose version in use is deleted, left out of [treeJson] and [unfiled].
  • List<Map<String, Object?>> get treeJson — The tree as the document writes it: a deleted occurrence gives its place to what it holds.
  • static PickedScript of(FilmProject project, Author? viewer) — Walks the project in use, resolving tags rather than pins and stopping repeats.

lib/src/plan.dart

• enum ImportState — The bounded wire state of an import, including the door’s dry-run state.
  • values: refused, proposed, checked, nothing
• enum ImportAction — The rule chosen for one patch against the viewer’s current pick.
  • values: update, fork, create, nothing, refused
• enum ImportStage — The independently retained stages of an import write.
  • values: create, content, pick
• class ImportChange — One detached, reviewed patch and the stages retained from earlier applies.
  • ImportChange({required this.id, required this.action, this.target, Map<String,dynamic>? before, required Map<String,dynamic> after, List<String> pa… — Snapshots content and stages so later caller edits do not change the review.
  • final ExchangeId id — The versionless file identity.
  • final ImportAction action — The action selected by the current pick and dry validation.
  • final Entity? target — The current pick the reviewed change starts from, absent for a creation.
  • final Map<String,dynamic>? before — The complete current content, absent for a creation.
  • final Map<String,dynamic> after — The complete proposed content, including preserved unknown fields.
  • final List<String> paths — The changed content paths, retaining ungrammatical root keys verbatim.
  • final List<String> removed — The explicitly removed paths.
  • final List<ImportNote> notes — Information shown beside this change, with structured payloads retained.
  • final ImportProblem? refused — The reason this change was refused, where applicable.
  • final Map<ImportStage,String?> done — Completed stages and their artifacts, never inferred from an identity alone.
• class ImportChangeInfo — A wire change containing identifiers and diagnostics rather than file content.
  • ImportChangeInfo(ImportChange change) — Copies the bounded portion of a reviewed change.
  • final String id — The versionless wire identity.
  • final ImportAction action — The planned action.
  • final String? target — The current source stem, absent for a creation.
  • final List<String> paths — The changed paths without their values.
  • final List<String> removed — The explicitly removed paths.
  • final List<ImportNote> notes — Information whose unknown kinds consumers retain.
  • final ImportProblem? problem — A refusal whose unknown code consumers treat as refused.
  • Map<String,Object?> get json — Serializes only the prescribed bounded fields (§6.18).
• class ImportAnswer — The content-free answer shared by dry checks and queued import doors.
  • ImportAnswer({required this.state, required List<ImportChangeInfo> changes, List<ImportNote> notes = const [], List<ImportProblem> problems = const… — Builds an answer without a proposal id, which belongs to the calling door.
  • final ImportState state — The plan state, or checked when a door performs a dry run.
  • final List<ImportChangeInfo> changes — The independent patches in application order.
  • final List<ImportNote> notes — Information about skipped document content.
  • final List<ImportProblem> problems — Document diagnostics, including nonfatal duplicate patches.
  • Map<String,Object?> get json — Serializes the answer without documents or a door-owned proposal id.
• class ImportPlan — A pure import review whose writes are available only through a separate apply.
  • ImportPlan({required List<ImportChange> changes, List<ImportProblem> problems = const [], List<ImportNote> notes = const []}) — Retains ordered independent changes and document diagnostics.
  • final List<ImportChange> changes — Each decoded patch, including changes refused independently.
  • final List<ImportProblem> problems — Document diagnostics, including whole-document reader and alias refusals.
  • final List<ImportNote> notes — Information about document content read past.
  • ImportState get state — Computes the total state table with whole-document refusal first (§6.18).
  • bool sameAs(ImportPlan other) — Binds consent to targets, content, removals and diagnostic payloads (§3.6).
  • ImportAnswer toAnswer() — Builds the bounded wire answer without publishing before or after content.
• function ImportPlan planImport(FilmProject project, Author? viewer, Map<String,Object?> document, {Map<String,Object?>? base, Guards guards = Guards.enforce… — Plans patches on the viewer’s current picks without reading or writing a source.

lib/src/projection.dart

• variable const Set<String> neverExported — The nine file-header keys omitted from every entity projection.
• variable const Map<EntityType, Map<String, String>> identifiedLists — The lists whose entries compose field-locally by their stable key.
• class Projection — Content selected from a file, with the file’s name and project frame retained.
  • const Projection(this.name, this.paths) — Defines a named path projection whose label does not select whole-file rules.
  • final String name — The projection’s name, joined with + in encounter order when composed.
  • final List<FieldPath> paths — The paths selected in addition to a whole-file projection, or on their own.
  • static const everything — The whole entity file less the nine excluded header keys, including notes.
  • static const whole — The whole content less media, picks, preview, hooks and x.
  • static final summary — The kind, aliases and descriptive summaries, with the file’s frame.
  • static final synopsis — The kind and synopsis, with the file’s frame.
  • static const frame — The name and, for a project, its complete epoch declarations alone.
  • static final projectOverview — The project’s common descriptive fields, with its frame.
  • Projection union(Projection other) — Composes paths without losing whole-file rules or field-local list selection.
  • Map<String, dynamic> apply(Map<String, dynamic> content, EntityType type) — Selects copied content in file order, always keeping name and project epochs.
• function Map<String, dynamic> modelFacingMedia(Map<String, dynamic> content) — Copies a file for a model, dropping archived/deleted entries and exact references to them, in the entity’s media and in each block’s alike (§10.3).

lib/src/scope.dart

• class Scope — A frozen scope identity, argument contract and shared selection recipe.
  • const Scope({required this.name, required this.description, required this.arg, required this.select}) — Defines a scope without its own document placement or serialization.
  • final String name — The permanent identity; incompatible recipes require another name.
  • final String description — The scope’s description for callers discovering the registry.
  • final ArgSpec arg — The argument shape checked before selection.
  • final void Function(ScopeSelection into, ExchangeContext ctx) select — The selector and projection composition for this scope.
• class ArgSpec — The shape of a scope argument, including typed tag lists and named parts.
  • static const none — Accepts no argument.
  • const ArgSpec.tags(EntityType type) — Accepts a list of string tags for the given entity type.
  • ArgSpec.object(Map<String, ArgSpec> parts) — Accepts an object containing exactly the declared named arguments.
  • final String kind — The wire descriptor kind: none, tags or object.
  • final EntityType? type — The tag list’s entity type, absent for other shapes.
  • final Map<String, ArgSpec> parts — The object shape’s named argument contracts.
  • Map<String, Object?> get json — The discoverable wire descriptor, independent of a particular argument.
  • void check(Object? value) — Refuses the wrong shape before a selection callback can run.
• class ScopeSelection — Projections unioned per concrete identity before document assembly.
  • ScopeSelection() — Starts an empty selection for selector composition.
  • factory ScopeSelection.of(Scope scope, ExchangeContext ctx) — Checks the argument and then runs the scope’s recipe.
  • Map<ExchangeId, Projection> get projections — The assigned union projection for each concrete file identity.
  • void add(Selector selector, Projection projection, ExchangeContext ctx) — Expands group epochs before composing projections, so overlapping ids share one union.
• class ScopeRegistry — The ordered registry of permanent scope names.
  • ScopeRegistry(Iterable<Scope> entries) — Snapshots the registered recipes and refuses duplicate names.
  • final List<Scope> entries — The recipes in discovery order.
  • Scope? named(String name) — Finds a recipe by its permanent name.
• variable final all — Every document of the film in use, whole, for handover.
• variable final projectOverview — The project in brief and the entities and script in summary.
• variable final sceneWithContext — Named scenes and their closure whole, with siblings and folders in synopsis.
• variable final locationUsage — Named locations whole and the scenes set there in synopsis.
• variable final characterArc — Named characters at their used epochs and their scenes whole, with ancestor synopses.
• variable final folderWhole — Named folders and their descendants whole, with ancestor synopses.
• variable final characterLines — Named characters’ dialogue, retaining each scene’s name and synopsis.
• variable final sceneDialogue — Named scenes whole, with every other scene, every character and the scenes’ folders above them in synopsis.
• variable final focus — The project frame and story in brief, with named folders and scenes and their closure whole.
• variable final scopeRegistry — The nine shipped scopes, each composed on the shared selection vocabulary.
• function List<Map<String,Object?>> scopes() — Lists each scope’s name, description and argument descriptor in registry order.
• class ExchangeContext — The viewer’s indexed film and inputs shared by selection and assembly.
  • ExchangeContext({required FilmProject project, required this.viewer, this.arg}) — Builds a context of the project version the viewer has in use.
  • final FilmProject project — The project after applying its viewer selection.
  • final Author? viewer — The handle resolution runs for, or null.
  • final Object? arg — The original scope argument, checked before the scope runs.
  • late final PickedScript script — The one picked walk every structural selector reads.
  • final List<ExchangeProblem> problems — Problems found while selecting references and arguments.
  • String get projectTag — The folder manifest’s tag, falling back to an indexed project tag.
  • List<String> tags(EntityType type, {String? part}) — Normalizes typed stems in the argument or a named part and reports invalid or missing tags individually.
  • Pick? pickOf(ExchangeId id, {bool report = true}) — Reads concrete picks, with the project identity naming the explicitly selected project.
  • Entity? resolveRef(EntityType type, String reference, {String? epoch, bool explicit = false}) — Resolves tags and typed references through viewer picks with explicit or implicit epochs.

lib/src/selectors.dart

• typedef typedef CueGrouping — The cues of a project by the group key of their owner, as the format’s cueGroupsByOwner answers.
• typedef typedef Selector — A reusable selection of versionless identities from the viewer’s context.
• extension SelectorCombinators — Selection filters composed without knowing document placement or serialization.
  • Selector where(bool Function(ExchangeId) keep) — Keeps identities satisfying the given predicate.
  • Selector ofType(EntityType type) — Keeps identities of the given format type.
• class Selectors — Shared identity selectors and the scene closure, independent of projections.
  • static Iterable<ExchangeId> project(ExchangeContext ctx) — Selects the project file in use.
  • static Iterable<ExchangeId> everything(ExchangeContext ctx) — Selects the manifest, all exchanged versions in use, and every render receipt.
  • static Selector ofType(EntityType type) — Selects concrete epoch ids of a type, excluding the shared library’s catalogue.
  • static Selector ids(Iterable<ExchangeId> list) — Selects the versionless ids given, including group ids.
  • static Selector scenes(Iterable<String> tags) — Selects named scenes and reports tags no scene has.
  • static Selector inScenes(Selector scenes, {CueGrouping groupCues = cueGroupsByOwner}) — Selects each named scene’s characters, outfits, setting, resources, shots and cues.
  • static Selector siblingsOf(Selector scenes) — Selects other scenes in the same picked lists as any given scene occurrence.
  • static Iterable<ExchangeId> folders(ExchangeContext ctx) — Selects every drawn and unfiled folder, in natural tag order.
  • static Selector foldersAbove(Selector entries) — Selects ancestors of every given occurrence in the picked script.
  • static Selector descendantsOf(Iterable<String> folderTags) — Selects descendants through each named folder’s picked children, stopping cycles.
  • static Selector scenesAt(Iterable<String> locationTags) — Selects scenes at any resolved epoch of the named locations.
  • static Selector scenesWith(String characterTag) — Selects scenes casting the character or naming it as a block speaker.
  • static Selector epochsUsedBy(String characterTag, Selector scenes) — Selects the character at every epoch the given scenes resolve it at.