filmopen_render

A snapshot

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

Renders asked for anywhere in the application, run in one queue that needs no film (Software Specification §6.15). Pure Dart: it depends on filmopen_jobs and filmopen_format and nothing else of FilmOpen, and imports no Flutter and no library the web build lacks, so that a render can run where no film and no screen is — a peer’s request through a later sharing service among them. A test holds that boundary (test/boundary_test.dart).

pure Dart. 12 files, 4,764 lines under lib/; 273 tests in 13 files. Barrel: lib/filmopen_render.dart.

Depends on

• filmopen_jobs — uses JobAction, JobPhase, JobUnavailable, JobView, Produced, ProducedItem, Producer, ProducerEvent, ProducerFailed, ProducerRun, ProducerState
• filmopen_format — uses Author, Entity, EntityType, ExactDecimal, FileNameParser, FilmProject, MediaKind, MediaStage, Money, MoneyBasis, RenderTreatment, UsageBasis, VersionStem, chargedFailure, frozenJson, newUsageId, sameJson

Used by

filmopen_app, filmopen_plugin_host, filmopen_render_ui

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/backend_render_manager.dart

• typedef typedef RenderReport — A diagnostic a manager reports: a code, and the error where one was caught, which the sink logs with its message.
• typedef typedef RenderEvent — A step of an operation the manager reports, as an event and its fields.
• class BackendRenderManager — The render manager over a backend, queueing each request on its scheduling resource.
  • BackendRenderManager({ required this.backend, required this.journal, this.retry = const Duration(seconds: 5), this.kept = 100, this.report, this.ev… — A manager using [retry] where a pending job gives no hint and keeping [kept] terminal jobs in its journal.
  • final RenderBackend backend — What runs each render.
  • final RenderJournal journal — Where the renders are kept between sessions.
  • final Duration retry — The wait before a pending job is asked about again, where its plug-in gives none.
  • final int kept — How many completed renders are retained by completion order, independently of public submission order.
  • final RenderReport? report — Told of what went wrong in the manager itself, by code.
  • final RenderEvent? events — Told of each operation and its steps: a submission, an admission, a send, a collection, an answer settled, a keep, a finish, an acknowledgement, an action, a write, a close, a person’s Stop (render.stop), a restore…
  • final ServerHold? Function(RenderDestination destination)? holdServer — A claim on the lease of the server a render runs on; the application’s server sessions’ where none is given.
  • static const unclaimedFor — How long a restored queued render waits for its producer before it is given up, never sent.
  • static const collectionRetries — An ordinary unanswered poll gets three automatic retries, after one, two and four seconds.
  • Future<void> get whenRead — Completes once the journal is read, at once where no restore began.
  • bool get restoredWhole — Whether the last session’s journal was read: where it was not, what its renders staged is kept.
  • Set<String> get held — The staged outputs the renders hold: what a sweep keeps.

lib/src/lending_route.dart

• function bool holdsStack(ServerSession session, String? stack) — Whether [session] may serve a share of [stack] (revision 18): it holds that stack, or names none — a server from before stacks —, or [stack] is null — the editor asking what a server offers before a stack is chosen.
• function ServerSession? runningSession(Iterable<ServerSession> sessions, ({String provider, String offer}) server, {String? stack}) — The running session of [server] among [sessions] that holds [stack], or null: a session of that provider started from that offer whose phase is running — not starting, whose candidate is not ready yet.
• function Map<String, Object?> lendingMatch(Iterable<ServerSession> sessions, ({String provider, String offer}) server, String? stack) — Which running server of [server] serves a share of [stack], and why, as the lending log records it (revision 18): the running sessions of that provider and GPU offer with the stacks they hold, the one chosen, and the…
• function (RenderRoute, RenderDestination?)? lendingRoute(List<RenderCandidate> candidates, String tag, ({String provider, String offer})? server, String? st… — The route a job of the plug-in [tag] on [server] runs on, with [stack] — the frozen declaration’s — set, and its destination: for this computer ([server] null), the plug-in’s candidate with no destination (never a ser…

lib/src/render_backend.dart

• class RenderNotReady — Why a route cannot run a model now, as codes the dialog says in words.
  • static const consent — The plug-in has not been allowed to run.
  • static const noKey — No key is saved for its platform.
  • static const notSignedIn — The route’s plan slot is not signed in.
  • static const noGrant — A key is saved, and the plug-in may not use it.
  • static const noServer — No server is set, or the one named is not there.
  • static const off — The plug-in is turned off.
  • static const newerApp — The plug-in needs a newer FilmOpen.
  • static const updateRequired — The plug-in was written for an earlier FilmOpen and must be updated before it renders.
  • static const noStack — None of the route’s ways of running the model is ready ([RenderStack.issues] says why).
  • static const serverStarting — The server it would run on is still starting.
  • static const throughConsent — The platform plug-in it runs through has not been allowed to run ([RenderCandidate.through] names it).
  • static const throughOff — The platform plug-in it runs through is turned off.
  • static const throughNewerApp — The platform plug-in it runs through needs a newer FilmOpen.
  • static const throughMissing — A plug-in it calls to reach its platform is not installed ([RenderCandidate.through] names it by its tag).
• class RenderCandidate — One way a model can run here, with whether it can now and the resource it would queue on: a route that can run in several places — the person’s own ComfyUI, a server a provider started — is one candidate for each.
  • const RenderCandidate({ required this.route, this.destination, required this.label, required this.bills, this.funding = 'key', required this.ready,… — A candidate.
  • final RenderRoute route — The plug-in and platform, with the key it would be sent on.
  • final RenderDestination? destination — Where it would run, which tells apart the candidates of one route; null where the route has no choice.
  • final String label — The person’s words for it: This computer’s ComfyUI, fal, a server’s name.
  • final bool bills — Whether it spends money on a key, where running on the person’s own machine does not.
  • final String funding — The decided funding origin: key, credit, plan, local, server or lent; a destination supplies its own label.
  • final bool manual — Whether this route is offered only for an explicit choice, never a first-ready default.
  • final bool ready — Whether it can run now.
  • final String? notReady — Why not: one of [RenderNotReady]’s codes.
  • final String? through — The platform plug-in the route runs through — by name, or by tag where not installed — where [notReady] is its.
  • final String? keyOf — The plug-in whose own key the route sends on, by its name, where [notReady] is that none is saved; null where the key is the application’s own.
  • final RenderResource resource — The resource it would queue on.
  • final bool speaksInVoice — Whether a line spoken on it is spoken in a voice the character keeps on its platform (Project Specification §9.1): its plug-in makes voices, and a request names the voice by the parameter voice.
• class RenderIssue — Something that stands in a stack’s way or would make it better, as the plug-in said it: its code, which the application acts on, and its words for the person.
  • const RenderIssue(this.code, this.message) — An issue.
  • final String code — The plug-in’s own code: missing_model, out_of_memory.
  • final String message — The plug-in’s words, in the person’s language.
• class RenderStack — One of a plug-in’s ways of running a model, with whether it is ready here and what it takes.
  • RenderStack({ required this.id, this.label, required this.ready, List<RenderIssue> issues = const [], Map<String, Map<String, Object?>> params = co… — A stack; its maps are copied and frozen.
  • final String id — The plug-in’s own id for it.
  • final String? label — The person’s words for it.
  • final bool ready — Whether it can run now.
  • final List<RenderIssue> issues — What stands in its way, or would make it better.
  • final Map<String, Map<String, Object?>> params — The choices this stack offers, by the catalogue’s parameter names, each as the contract’s OptionSpec holds it: over the route’s own of the same name.
  • final Map<String, Object?> needs — What it asks of the machine it runs on: its memory, its files.
• class RenderOptions — A route’s options for a model, including its readiness, choices, price and retryable busy inspection.
  • RenderOptions({ List<RenderStack> stacks = const [], this.suggested, Map<String, Map<String, Object?>> params = const {}, this.quote, this.busy = f… — Options; the maps are copied and frozen.
  • final List<RenderStack> stacks — The route’s ways of running the model, each with its readiness.
  • final String? suggested — The stack to start at: a ready one.
  • final Map<String, Map<String, Object?>> params — The choices every stack offers, by the catalogue’s parameter names, each as the contract’s OptionSpec.
  • final RenderQuote? quote — The price of the choices asked about; null where the route gives none.
  • final bool busy — Whether this options inspection is busy and may be asked again.
  • final DateTime? retryAt — When a busy options answer may be asked for again, in UTC.
• enum RenderServicePhase — Where a pending render is at its service, as the interface’s pending phase says.
  • values: queued, running, downloading
• enum RenderCancelState — What a service says of a render it was asked to stop, as the interface’s Cancelled says.
  • values: cancelled, finished, unknown
• class RenderOutcome — How one call of a render ended, or that it has not yet.
  • const RenderOutcome() — An outcome.
• class RenderSucceeded — It made its outputs, each staged by the backend and opened by it alone, never an address to fetch.
  • RenderSucceeded(List<RenderOutput> outputs) — A success.
  • final List<RenderOutput> outputs — The outputs, in the order the plug-in gave them, previews left out.
• class RenderPending — The service accepted the work and it goes on: [receipt] is the plug-in’s record of it, for collect and cancel.
  • RenderPending(Map<String, Object?> receipt, {this.phase, this.progress, this.retryAfter, this.charged = false}) — A job the service holds; [receipt] is copied and frozen.
  • final Map<String, Object?> receipt — The backend’s record of the work, kept as it came: the plug-in’s Job, and what the backend keeps with it.
  • final RenderServicePhase? phase — Where it is at the service, where the plug-in says.
  • final double? progress — 0 to 1, only where the service says.
  • final Duration? retryAfter — The plug-in’s hint of when to ask again; the manager keeps it between 1 and 60 seconds.
  • final bool charged — Whether a paid service took one of the call’s requests on a person’s key: the render’s job keeps it, so that a later call that fails — refused before it sends, or answered with no success — still says it may have cost.
• class RenderFailed — It failed, with its code; its cost is retained for durable terminal Usage settlement.
  • const RenderFailed(this.code, {this.retryable = false, this.stage, this.charged = false, this.confirmed = false, this.message}) — A failure.
  • final String code — The plug-in’s own code, or the application’s.
  • final String? message — The plug-in’s words for a person, screened and cut by the host before they arrive; carried, never read here.
  • final bool confirmed — Whether a canonical provider answer confirms the work ended, rather than a transport failing to answer.
  • final bool retryable — Whether the plug-in says trying again could work; the manager never tries again by itself.
  • final RenderStage? stage — Where it failed, where the plug-in says.
  • final bool charged — Whether a paid service took one of its requests, so that it may have been charged whatever it came to.
• class RenderBackend — The one door from the render manager to what runs a model: the plug-in host behind it in the application, a stand-in in a test.
  • Future<List<RenderCandidate>> candidates(String model) — Who can run [model] here, each with its readiness; the local ones first.
  • RenderResource resourceOf(RenderRequest request, {String? job}) — The resource [request] queues on: its route’s, and its destination’s where it names one.
  • Future<RenderOptions> options(String model, RenderRoute route, { Map<String, Object?> params = const {}, RenderDestination? destination, }) — What [route] offers for [model] now, and the price of [params] on it: nothing starts and nothing is spent.
  • Future<RenderOutcome> render(RenderRequest request, {required String job, Future<void>? stopped}) — Sends [request] on its route, the call bound to [job]; answers its outcome, or a pending receipt.
  • Future<RenderOutcome> collect(RenderRequest request, Map<String, Object?> receipt, { required String job, Future<void>? stopped, }) — Asks about work [render] left pending, bound as it was, and stopped as it would be.
  • Future<RenderCancelState> cancel(RenderRequest request, Map<String, Object?> receipt, {required String job}) — Asks the service to stop that work and no other, and answers what it says.
  • ProducedItem item(RenderRequest request, RenderOutput output) — [output] as the insertion takes it in: bytes the backend opens itself, with the provenance of [request].
  • Future<void> release(List<RenderOutput> outputs) — Lets go of what [outputs] staged, once they were taken in or the render was given up.
• class RenderSettlementBackend — A backend whose terminal effects follow the manager’s durable terminal journal.
  • void manage(String job) — Registers a managed job before its first call, so terminal effects await its journal.
  • Future<Map<String, Object?>> prepareSettlement(RenderJob job) — Prepares a nonempty opaque terminal payload without writing Usage or another external effect.
  • Future<void> settle(RenderJob job) — Applies a saved terminal payload idempotently by job, without collecting or rendering again.
• class RenderFactsBackend — A backend that hands the manager the facts of each render it runs, to be kept on the job as [RenderJob.facts].
  • void attachKeeper(Future<void> Function(String job, Map<String, Object?> facts, {RenderOutput? staged}) keep) — Gives the backend [keep], which it calls with a job’s facts as they become known, and with the output it [staged] where they belong to one.

lib/src/render_job.dart

• enum RenderPhase — A render’s lifecycle phase, also relayed by its producer.
  • values: queued, submitting, rendering, stopUnconfirmed, collectionUnconfirmed, settling, downloading, outputReady, done, failed, cancelled, interrupted
  • bool get isOver — Whether a render in this phase is over: nothing more happens to it by itself.
• enum RenderStage — Where in a render something went wrong, as the interface’s Problem.stage names it.
  • values: preparing, uploading, queued, running, downloading
• class RenderOutput — One output a render made, staged by the backend where it can be opened again after a restart: the backend’s own name for the bytes, never an address.
  • RenderOutput({ required this.ref, required this.name, required this.mime, this.length, this.seed, this.stack, Map<String, Object?> provenance = con… — An output; [provenance] is copied and frozen.
  • final String ref — The backend’s own name for the staged bytes, meaningful to it alone.
  • final String name — A file name the importer reads the kind from.
  • final String mime — The type the bytes were checked to be.
  • final int? length — How many bytes, where known.
  • final int? seed — The seed that made it, where the plug-in says.
  • final String? stack — The plug-in’s way of running the model that made it, as its answer names it, for the take’s record.
  • final Map<String, Object?> provenance — What the insertion writes with its take, as the backend made it when it staged the bytes: the run that made it and the record of what that run was asked (§12.2).
  • Map<String, Object?> toJson() — The output as a job holds it.
  • static RenderOutput? fromJson(Object? json) — An output as [toJson] wrote it, or null for one that is not.
• class RenderResource — A queue of renders that run on one thing — a ComfyUI server, a key’s account — as many at a time as its capacity.
  • const RenderResource(this.key, {required this.capacity}) — A resource.
  • final String key — Its name: the platform’s id and a digest of what stands behind it, the bound server or the key’s slot, so that two servers are two resources and two plug-ins on one server are one.
  • final int capacity — How many renders it takes at a time ([RenderCapacity.of]).
• class RenderCapacity — How many renders run at once (revision 2’s capacity).
  • static const ceiling — The manager’s own ceiling across every resource, so that a check, a key’s check and an action always find one of the host’s five calls free.
  • static int of({int? person, int? declared, required bool bills}) — A resource’s capacity: the person’s own number where they set one, else what its platform plug-in declares, else 1 on a platform of kind local and 2 on one that [bills]; a number below 1 is none.
• class RenderJob — One render as the manager knows it.
  • RenderJob({ required this.id, required this.request, required this.phase, required this.resource, this.progress, this.code, this.charged = false, t… — A job; [receipt] and [facts] are copied and frozen.
  • final String id — The job’s id, unique and kept across a restart: the ctx.job.id its calls are given.
  • final RenderRequest request — What was asked, as it was frozen.
  • final RenderPhase phase — Where it is.
  • final String resource — The resource label recorded when the render was submitted.
  • final double? progress — 0 to 1, only where the service says.
  • final String? code — For [RenderPhase.failed]: the failure’s code, the plug-in’s own or the application’s.
  • final bool charged — Whether a paid service took one of the render’s requests, from the call that took it to its last, so that a failure after it may have been charged.
  • final Map<String, Object?>? receipt — The backend’s record of work a service accepted — the plug-in’s Job and what the backend keeps with it — kept as it came and handed back to collect and cancel; null until the service answers pending.
  • final Map<String, Object?>? facts — The facts a RenderFactsBackend handed its keeper for this render, stored as given and interpreted by nothing here.
  • final Map<String, Object?> settlement — The backend’s prepared terminal effects, saved before they are applied and replayed idempotently.
  • final bool settlementApplied — Whether the prepared terminal effects were applied and that fact was kept in the journal.
  • bool get needsAttention — Whether this render needs a person’s retry or dismissal while retaining its resource.
  • final List<RenderOutput> outputs — From [RenderPhase.outputReady]: what it made, staged, in the order the plug-in gave them.
  • RenderJob next({ RenderPhase? phase, double? progress, bool clearProgress = false, String? code, bool clearCode = false, bool? charged, Map<String,… — This job moved on: [phase] and whatever else is given, the rest kept.
  • Map<String, Object?> toJson() — The job as a manager’s journal keeps it.
  • static RenderJob? fromJson(Object? json) — A job as [toJson] wrote it, or null for one that is not, in whole or in part.

lib/src/render_journal.dart

• variable const renderJournalVersion — The version of the render manager’s journal.
• class RenderJournal — Where a render manager keeps its renders between sessions: one JSON document, read when it restores and written after every change.
  • Future<Map<String, Object?>?> read() — The document last written, or null where none was.
  • Future<void> write(Map<String, Object?> state) — Keeps [state] in place of what was there.
  • Future<void> setAside() — Moves the document out of the way, kept as it was, so that the next [read] finds none.
• class MemoryRenderJournal — A journal in memory: what a test and a platform with no files keep.
  • MemoryRenderJournal([Map<String, Object?>? state]) — A journal holding [state], a copy of it.
  • int writes — How many times it was written.

lib/src/render_kinds.dart

• variable const renderEntryKinds — The catalogue kinds whose models make a medium: a picture’s image, a clip’s video, a voice sample’s tts.
• function MediaKind? renderMediaKindOf(String? entryKind) — The medium a model of the catalogue kind [entryKind] makes into a place, or null where no place takes it.
• variable const voiceDesignKind — The catalogue kind of a voice design model (ttv, Project Specification §14.6): previews of a voice described, to keep as a voice of the person’s account.

lib/src/render_manager.dart

• class RenderRefusal — Refusals a render manager answers, as codes the caller says in words ([RenderRefused.code]).
  • static const noManager — No manager is installed: the application has not started one, or this build renders nothing.
  • static const noJob — No render has that id.
  • static const journal — The render journal could not be read whole or accept a required durable write.
  • static const cleanup — An accepted render’s local staged-output cleanup did not complete; acknowledgment can retry it.
  • static const notReady — The render has no outputs to hand over: it is not at [RenderPhase.outputReady].
• function String newRenderJobId([Random? random]) — A render’s id for a manager that makes its own: a random UUID, which [isRenderJobId] holds.
• function bool isRenderJobId(String id) — Whether [id] has a render’s id’s form: 8 to 96 lowercase hexadecimal digits and dashes, the first a digit — what both the jobs’ journal takes for a job’s id and the insertion keeps as a producer’s recovery (Software S…
• class RenderRefused — A render manager’s refusal: a code of [RenderRefusal]’s, never a sentence.
  • const RenderRefused(this.code) — A refusal.
  • final String code — Why.
• class RenderManager — Every render of the application, one queue per resource, each as many at a time as its capacity and never more than [RenderCapacity.ceiling] in all, in the order asked.
  • static RenderManager current — The manager the application installed; [NoRenderManager] until it does.
  • Future<String> submit(RenderRequest request) — Queues [request] on its resource and answers its render id.
  • RenderJob? job(String id) — The render [id] as it is now, or null for none.
  • List<RenderJob> get jobs — Every render the manager holds, newest first.
  • Stream<List<RenderJob>> get changes — [jobs], each time one changes.
  • Stream<RenderJob> watch(String id) — The render [id] as it is now and at each change, ending once it is over ([RenderPhase.isOver]); an error [RenderRefused] of noJob for none.
  • Future<List<ProducedItem>> items(String id) — The outputs of the render [id], at [RenderPhase.outputReady], as the insertion takes them in — opened by the backend, after a restart too.
  • Future<void> acknowledge(String id) — Durably marks the render [id]’s accepted outputs done and completes their recoverable staged cleanup.
  • Future<bool> stop(String id) — Stops the render [id]: a queued one never starts; a call in flight is ended, and work a service holds is cancelled there, what it had finished still collected; staged outputs nobody took in are given up and let go, wh…
  • Future<void> pokeNow(String id) — Asks about [id]’s held work now instead of at its next poll: a lending notice said it changed (§6.6c).
  • Future<void> restore() — Reads what the last session left: a queued render stays queued, a pending one is asked about again, one whose outputs were staged is ready again, and one that was a single call in flight is [RenderPhase.interrupted],…
  • Future<void> close({Duration grace = const Duration(seconds: 10)}) — Lets the running calls end within [grace], and keeps every render’s state for [restore].
• class NoRenderManager — The manager before the application installs one: it holds nothing and renders nothing.
  • const NoRenderManager() — The empty manager.
• class RenderAttentionManager — The optional attention controls and safe job views of a render manager.
  • List<JobView> get views — The current render views, including held jobs needing attention.
  • Future<bool> act(String id, JobAction action) — Applies retry, dismiss or stop to a render without resubmitting an accepted job.

lib/src/render_producer.dart

• variable const renderProducerKind — The kind the insertion service knows a render’s producer by, and a ProducerSource’s kind names.
• variable const renderRunJobKey — The one key of a render run’s saved JSON, id, holding the render’s id ([isRenderJobId]): the form the insertion keeps as a producer’s recovery, and that restore attaches to again.
• class RenderProducer — A render as the insertion service is handed it, over [RenderManager]: start submits its source’s request — a [RenderRequest]’s JSON — and the run relays watch as [ProducerState]s named by [RenderPhase]; at `output…
  • const RenderProducer() — A producer of renders.
• class ManagedRenderProducer — The render producer over the installed manager ([RenderManager.current]): start submits the request it is handed, and a run relays the render’s phases until its outputs are ready, then hands them over.
  • const ManagedRenderProducer() — The producer.

lib/src/render_request.dart

• enum RenderOrigin — Where a render comes from: this application, or a peer’s request through a sharing service.
  • values: local, remote, developer
• class RenderRoute — The way a render runs: the plug-in that answers for the model, on its platform, with the key and the way of running it the person chose.
  • const RenderRoute({required this.plugin, required this.platform, this.keyId, this.stack, this.program}) — A route.
  • final String plugin — The plug-in’s tag: fo-cui-zimage.
  • final String platform — The catalogue’s platform id: comfyui, fal.
  • final String? keyId — The id of the key the render is sent on, <owner>:<slot>; never its value, and null where none is.
  • final String? stack — Which of the plug-in’s ways of running the model, as its options named it.
  • final String? program — The machine program setting used by this route, or null for a route without a program.
  • Map<String, Object?> toJson() — The route as a request holds it.
  • static RenderRoute? fromJson(Object? json) — A route as [toJson] wrote it, or null for one that is not.
• enum RenderDestinationKind — What kind of place a render runs in.
  • values: local, server, lent
• class RenderDestination — Where a render runs, as the application bound it: never an address and never a credential.
  • RenderDestination({required this.id, required this.kind, this.label, this.provider, Map<String, Object?>? server}) — A destination; [server] is copied and frozen.
  • final String id — The application’s own name for it, the same for as long as it stands: with [kind], what it is.
  • final RenderDestinationKind kind — Where it is.
  • final String? label — The person’s words for it.
  • final String? provider — For a server: the server-provider plug-in’s tag.
  • final Map<String, Object?>? server — For a server: the provider’s own reference to it, opaque here and handed back as it is; or a lent offer: its version, the price shown and the quantities it was priced at.
  • Map<String, Object?> toJson() — The destination as a request holds it.
  • static RenderDestination? fromJson(Object? json) — A destination as [toJson] wrote it, or null for one that is not.
• class RenderQuote — A price a render was shown at, with where it came from ([UsageBasis]): its cost’s own basis, or unknown and no cost at all.
  • RenderQuote(Money this.cost, {this.per, this.id, DateTime? quotedAt, DateTime? validUntil}) — A price, whose basis is its cost’s own; its times are kept in UTC.
  • RenderQuote.unknown({this.id, DateTime? quotedAt, DateTime? validUntil}) — A price nobody knows: no cost, and never one of nothing.
  • final UsageBasis basis — Where the price came from.
  • final Money? cost — The price, in the platform’s currency; null where nobody knows it.
  • final String? per — What one [cost] buys where it is not the whole render: hour, for a server’s lease.
  • final String? id — The service’s own name for the quote, handed back to the plug-in with the render it priced.
  • final DateTime? quotedAt — When the price was read, in UTC.
  • final DateTime? validUntil — The last moment the price holds, where the platform says, in UTC.
  • Map<String, Object?> toJson() — The quote as a request holds it.
  • static RenderQuote? fromJson(Object? json) — A quote as [toJson] wrote it, or null for one that is not: a basis that is not its cost’s own, a cost where the basis is unknown, or a date that is not one.
• variable const renderSeedMost — The largest seed a render takes, as the interface’s render does.
• class RenderRequest — One render, as the person asked for it, frozen when they did: nothing the dialog, a setting or the film says afterwards changes what it is, and it holds no credential and no address.
  • RenderRequest({ required this.model, required this.route, this.destination, required this.prompt, Map<String, Object?> params = const {}, this.seed… — A request, whose maps and lists are copied and frozen.
  • final String model — The catalogue entry’s id: t2i-z-image-turbo.
  • final RenderRoute route — The plug-in, platform, key and stack the render runs on, as the person chose them.
  • final RenderDestination? destination — Where it runs, where the route has a choice of servers.
  • final String prompt — The prompt, composed once: the entity’s own first, then the treatment’s (Project Specification §8.7).
  • final Map<String, Object?> params — The options chosen, by the catalogue’s parameter names; a negative prompt is one of them, negative_prompt, where the model takes one.
  • final int? seed — The seed the person gave, to make a render again; null for a new one each time.
  • final Map<String, Object?> inputs — The film’s media given to the model, by the catalogue’s input names: a reference, or a list of them.
  • final RenderQuote? quote — The price the person was shown, which is the price of this route and these options.
  • final Map<String, Object?> target — The place the outputs go, as the insertion’s InsertionTarget writes itself: its project, its stem, its place and group, captured when the person asked.
  • final String? source — The stem of the version the render is of, where it is of one.
  • final SourceSnapshot? primarySnapshot — The exact primary source and its caller-supplied hash, naming [source] when present.
  • final List<SourceSnapshot> sourceDependencies — The dependency sources and their caller-supplied hashes, copied and frozen with the request.
  • final RenderTreatment? treatment — The visual treatment that applied when the person asked, with where each leaf came from — the shape its batch item keeps as treatment (Project Specification §12.2); null where none did.
  • final String? purpose — What the render is for, in the target’s word: reference, sheet, first_frame.
  • final MediaStage stage — The stage the person asked at (§12.2): prototype unless they chose another.
  • final Map<String, Object?>? from — The take the render continues, as the record keeps it; null where it continues none.
  • final RenderOrigin origin — Who asked.
  • final DateTime askedAt — When the person asked, in UTC.
  • bool isAt(Map<String, Object?> place) — Whether this request’s outputs go to [place], an InsertionTarget as it writes itself.
  • Map<String, Object?> toJson() — The request as a job’s payload holds it: JSON, with no credential and no address.
  • static RenderRequest? fromJson(Object? json) — A request as [toJson] wrote it, or null for one that is not, in whole or in part: a job restored from its journal reads it here.

lib/src/server_sessions.dart

• class ServerAnswer — What a server provider answered one call of its interface.
  • const ServerAnswer() — An answer.
• class ServerAnswered — The provider answered [value], which the backend has held to the definition.
  • const ServerAnswered(this.value) — An answer.
  • final Map<String, Object?> value — The answer’s JSON.
• class ServerUnanswered — No answer came: the plug-in was off, refused or failed, or ran out of time.
  • const ServerUnanswered(this.code) — A call with no answer, and why.
  • final String code — The application’s code: notFound, refused, timeout.
• class ServerProvider — An enabled server provider: its plug-in’s tag and name, and the platform its key manages servers on.
  • const ServerProvider({required this.tag, required this.name, this.platform, this.platformName}) — A provider.
  • final String tag — The plug-in’s tag: fo-salad.
  • final String name — The plug-in’s name, in the person’s language.
  • final String? platform, platformName — The platform of the key its servers are made with, and its platform file’s name for it: SaladCloud.
  • String get label — What a person calls it: its platform’s name, else the plug-in’s.
• class ServerBackend — The door from the server sessions to the server-provider plug-ins: the host in the application, a stand-in in a test.
  • List<ServerProvider> providers() — The server providers enabled now.
  • Future<ServerAnswer> call(String provider, String function, Map<String, Object?> args, { DateTime? deadline, Future<void>? cancelled, }) — Calls [function] of the server-provider interface on [provider].
  • Future<void> recordUsage(ServerUsage usage) — Keeps [usage] in the usage log.
• class ServerCapabilities — What a provider does, as its serverCapabilities says.
  • const ServerCapabilities({ required this.engines, this.idleDefault = 15, this.idleMin = 5, this.idleMax = 60, this.providerStops = false, this.stac… — Capabilities.
  • final List<String> engines — The engines its servers run: comfyui, wan2gp.
  • final List<ServerStack> stacks — The model stacks a server can be deployed with (revision 18); none for a provider that names none.
  • final int idleDefault, idleMin, idleMax — The inactivity minutes a person starts at, and the fewest and most they may choose.
  • final bool providerStops — Whether the provider itself stops a server when its lease runs out.
  • bool allows(int minutes) — Whether [minutes] is a lease a person may choose.
  • static ServerCapabilities? fromJson(Map<String, Object?> json) — Capabilities as the interface answers them, or null for an answer that says no engine and no idle range.
• class ServerStack — One model stack a provider can deploy a server with, as its serverCapabilities lists it (revision 18).
  • const ServerStack({ required this.id, required this.engine, required this.label, required this.requiredVramGB, this.downloadGB, this.coldStartMinut… — A stack.
  • final String id — What deployServer is sent as stack.
  • final String engine — The engine it runs on.
  • final String label — The provider’s words for it.
  • final double requiredVramGB — The least VRAM an offer must have to hold it.
  • final double? downloadGB, coldStartMinutes — What a server downloads at boot, and the minutes it takes to start, an estimate; null where not given.
  • bool fits(num? vramGB) — Whether an offer of [vramGB] holds it: one whose VRAM is not given holds none.
  • static ServerStack? fromJson(Object? json) — A stack as the interface lists it, or null for a row without its id, engine, label or VRAM.
  • Map<String, Object?> toJson() — The stack as the log records it.
• class ServerOffer — One server configuration in a provider’s catalogue, with the whole hourly price of its resources.
  • const ServerOffer({ required this.id, required this.label, required this.hourlyUsd, this.gpuClass, this.vramGB, this.priority, this.available, }) — An offer.
  • final String id — What a deployment is given to start one.
  • final String label — The provider’s words for it: RTX 4090 (24 GB).
  • final double hourlyUsd — The whole hourly price, in US dollars.
  • final String? gpuClass — The provider’s id of its GPU.
  • final int? vramGB — Its GPU’s memory, in gigabytes.
  • final String? priority — The provider’s priority for it: batch, low, medium, high.
  • final int? available — How many the selected-class check says could start now, or null for unchecked or unknown capacity.
  • static ServerOffer? fromJson(Object? json) — An offer as the interface answers it, or null for one with no id, label or price.
• enum ServerQuotaState — The state of a provider’s optional raw quota.
  • values: known, exhausted, malformed
• class ServerQuota — The provider’s raw container-replica quota decoded without treating absence as zero.
  • final ServerQuotaState state — Whether the quota is usable, exhausted or malformed.
  • final num? quota, used — The finite non-negative quota and use, where both were readable.
  • String? get refusal — Why this quota refuses deployment, or null where capacity remains.
  • static ServerQuota fromJson(Object? value) — Decodes a present raw /quotas value; unreadable values fail closed.
• class ServerQuote — A provider’s catalogue or selected-class check, as serverOffers answered at [quotedAt].
  • ServerQuote({required this.provider, required List<ServerOffer> offers, required DateTime quotedAt, this.checkedOffer, this.quota}) — A quote; its time kept in UTC and its offers frozen.
  • static const holds — How long a quote holds for a deployment: a provider asks for a fresh one after five minutes.
  • final String provider — The provider’s tag.
  • final List<ServerOffer> offers — Its offers, the cheapest first as the provider gave them.
  • final ServerOffer? checkedOffer — The uniquely matched offer of a selected check; null for a catalogue.
  • final ServerQuota? quota — The optional raw quota decoded; absence leaves the provider’s deployment gate in force.
  • final DateTime quotedAt — When the prices were read.
  • bool expiredAt(DateTime now) — Whether the quote no longer holds at [now].
  • ServerOffer? matching(ServerOffer offer) — The held offer matching id, GPU class and priority, or null for an ambiguous or missing match.
  • String? refusalFor(ServerOffer offer) — Why this quote cannot authorize [offer], including unchecked, unknown or zero capacity and unreadable quota.
  • static ServerQuote? fromJson(String provider, Map<String, Object?> json, {ServerOffer? selected}) — Reads a catalogue or check; malformed rows fail closed and catalogue counts are discarded.
• enum ServerState — A server’s state in the interface’s words, whatever its provider’s own.
  • values: pending, starting, running, stopping, stopped, expired, unknown
• class ServerStatus — A server as its provider sees it now, the interface’s ServerStatus, its endpoint left with the host.
  • ServerStatus({ required Map<String, Object?> server, required this.state, this.providerState, this.label, this.running, this.expiresAt, this.engine… — A status; [server] is copied and frozen.
  • final Map<String, Object?> server — The provider’s own reference to it, handed back as it is.
  • final ServerState state — Its state.
  • final String? providerState — The provider’s own word for it.
  • final String? label — The provider’s words for it.
  • final int? running — How many of its instances run.
  • final DateTime? expiresAt — When the provider stops it unless it is kept awake.
  • final String? engine — The engine it runs: comfyui.
  • final String? stack — The id of the model stack it holds (revision 18), or null where its provider names none.
  • String? get name — Its deployment name: the reference’s name.
  • static ServerStatus? fromJson(Object? json) — A status as the interface answers it, or null for one with no reference.
• class ServerFailure — A provider’s refusal, as its Failed answer says it, or the application’s.
  • const ServerFailure(this.code, [this.message]) — A refusal.
  • final String code — The provider’s code (quote-expired, capacity-changed) or the application’s (unanswered).
  • final String? message — The provider’s nonblank words for it, which the sessions show and log.
  • static ServerFailure? of(Map<String, Object?> value) — The refusal in [value], an answer whose state is failed, or null for an answer that is not one.
• class ServerSessionRefused — A refusal of the sessions’ own, before anything is asked of a provider.
  • const ServerSessionRefused(this.code) — A refusal, with one of [ServerSessions]’ codes.
  • final String code — quoteExpired, idleMinutes, noOffer, busy, journal, noServer, noSession, providerOff.
• enum ServerSessionPhase — Where a server session is.
  • values: deploying, uncertain, starting, running, stopping, stopped, expired, failed
  • bool get isOver — Whether nothing more is spent or can be stopped.
• class ServerSession — One server a person started for renders, as the sessions keep it: never an address or a key.
  • ServerSession({ required this.name, required this.provider, required this.offerId, required this.offerLabel, required this.hourlyUsd, required this… — A session; [server] is copied and frozen.
  • final String name — Its deployment name, made by the application and kept before the provider is asked: the session’s id.
  • final String provider — The server provider’s tag.
  • final String offerId, offerLabel — The offer it was made of, and the provider’s words for it.
  • final double? hourlyUsd — Its quoted hourly price in US dollars; unknown for a server found at the provider.
  • final int idleMinutes — Its lease, in minutes of inactivity.
  • final DateTime askedAt — When the person asked for it.
  • final ServerSessionPhase phase — Where it is.
  • final Map<String, Object?>? server — The provider’s own reference to it, once it answered; null for a server not yet answered.
  • final String? providerState — The provider’s own word for its state.
  • final DateTime? expiresAt — When its provider stops it unless it is kept awake, as the provider last said.
  • final DateTime? runningSince, endedAt — When it was first seen running, and when it was seen stopped.
  • final String? problem, problemText — The last refusal’s code, and the provider’s words for it, which are not kept across a restart.
  • final bool found — Whether its provider listed it and no session of this application had asked for it.
  • final String? usage — The id of its usage’s first record, once written.
  • final bool usageEnded — Whether its usage’s last record is written.
  • final bool capSaid — Whether the log has said its start’s cap stopped its renewals: said once per session, never kept in the journal.
  • final String? engine — The engine it runs, as its provider said: comfyui, the platform a render’s route names.
  • final String? stack — The id of the model stack it holds: as its provider said, else as it was deployed with; null for a server of a provider that names no stacks, which serves any share of its offer.
  • final bool stopOwed — Whether its lease ran out with no instance running while its provider still held it starting or running — a start not yet called off, an instance being placed again — so that its stop is owed until its provider holds…
  • final DateTime? seenRunningAt — When its provider was last seen holding it running with an instance counted: a lease that lapsed after it ran until then at least (§6.15).
  • bool get takesWork — Whether a render may be sent to it: it starts or runs, and no stop was asked.
  • bool get unsure — Whether it was made and its provider no longer lists it: it may still run, and its stop is asked by its name.
  • DateTime? get deadline — When its lease runs out: [expiresAt] as its provider last said, else [idleMinutes] after it was asked for; none for a server found at its provider with no [expiresAt] (§6.15).
  • RenderDestination get destination — Where a render runs on it: its destination, the same for as long as the session stands.
  • ServerSession copyWith({ ServerSessionPhase? phase, Map<String, Object?>? server, String? providerState, DateTime? expiresAt, DateTime? runningSinc… — A copy with what changed.
  • Duration runningFor(DateTime now) — How long it has run by [now]: from [runningSince] to [endedAt], or to [now] while it runs.
  • Map<String, Object?> toJson() — The session as the journal keeps it.
  • static ServerSession? fromJson(Object? json) — A session as [toJson] wrote it, or null for one that is not.
• class ServerUsage — A compute session’s usage: its running time and the quoted hourly price make an estimate, never a bill, which no request to its provider’s management is.
  • const ServerUsage({ required this.session, required this.id, this.ref, required this.ended, required this.at, required this.running, this.estimate, }) — A record’s worth of usage.
  • final ServerSession session — The session it is of.
  • final String id — The record’s id.
  • final String? ref — Its chain’s first record’s id, which the first itself has not.
  • final bool ended — Whether it is the last record: the server stopped, or its lease ran out.
  • final DateTime at — When it was written.
  • final Duration running — How long the server ran: nothing, on the first record.
  • final Money? estimate — What it is expected to cost: its lease at the quoted price on the first record, its running time on the last; null where no price was quoted.
  • ExactDecimal get minutes — Minutes, as a usage record holds them.
• class ServerHold — A job’s claim on a server’s lease: the lease is renewed while one is held.
  • ServerHold(this._release) — A claim that [release] lets go of, once.
  • void release() — Lets go of the claim; a second call does nothing.
• class ServerSessions — Every server the person started for renders: a quote, a deployment named and kept before it is asked for and never asked for twice, its lease renewed while a job runs on it or it starts, a stop confirmed by its provid…
  • ServerSessions({ required this.backend, required this.journal, DateTime Function()? clock, Random? random, this.tickEvery = const Duration(seconds:… — Sessions over [backend], kept in [journal]; [clock] and [random] are a test’s to give.
  • final void Function(String event, Map<String, Object?> data)? report — Told what the sessions concluded or could not keep, as an event and its data — a provider’s tag, an error’s type, never an address: the application’s log.
  • static const missesToConclude — How many of its provider’s lists may lack an unanswered deployment’s name before it is taken as never made.
  • static const unsureEvery — How often a server its provider no longer lists is looked for (§6.15): its provider’s list is a request on the person’s key, and a list answered past its lease’s deadline that still lacks it is what settles it.
  • static ServerSessions? current — The sessions the application installed; null where it installed none.
  • final ServerBackend backend — The door to the providers.
  • final RenderJournal journal — Where the sessions are kept between runs of the application.
  • final Duration tickEvery — How often a starting, stopping or held server is looked after.
  • final Duration startupCap — How long a start is kept alive by renewals before only a job can keep it: a start that never finishes must not keep spending.
  • final Duration leaseGrace — How long past its lease’s deadline a server its provider still runs is left to its provider’s own schedule before this application asks for its stop (§6.15).
  • List<ServerProvider> get providers — The providers enabled now, as the backend lists them; reading them changes nothing.
  • String labelOf(String tag) — What a person calls the provider [tag]: its label, the last one known — kept in the journal — where it is turned off, else its tag.
  • bool get anyLive — Whether the servers’ panel has anything to show where no provider is on: a server that may still cost.
  • bool providerOn(String tag) — Whether the provider [tag] is enabled now.
  • bool stopNotCarriedOut(ServerSession session) — Whether [session]’s stop was taken by its provider and not carried out: it still holds it running, an instance counted, and the stop is asked again (§6.15).
  • List<ServerSession> get sessions — Every session, the newest first.
  • Stream<List<ServerSession>> get changes — [sessions], each time one changes.
  • ServerSession? session(String name) — The session [name], or null for none.
  • List<ServerSession> runningEngine(String engine) — The sessions a render may be sent to whose servers run [engine]: starting or running within their lease, their provider on, newest first — one past its lease is being stopped, and one whose provider is off cannot be k…
  • bool overran(ServerSession session) — Whether [session]’s lease has passed while its provider still says it starts, runs or stops — its own schedule late: by this application’s clock, what its row says in place of the deadline, and why no render is sent t…
  • String? unconfirmed(ServerSession session) — Why [session]’s end is unknown past its deadline — its provider turned off (providerOff), its provider’s last list not answered in this run (unanswered), or its provider still saying it stops (stillStopping) — o…
  • Duration runningFor(ServerSession session) — How long [session] has run by now, as its row and its estimate say: no later than its deadline — or than when its provider was last seen running it, past that — while its end is [unconfirmed] (§6.15).
  • ServerSession? sessionOf(RenderDestination destination) — The session whose destination [destination] is, or null for none.
  • Future<ServerCapabilities?> capabilities(String provider, {DateTime? deadline, Future<void>? cancelled}) — What [provider] does, asked once a run.
  • Future<(ServerQuote?, ServerFailure?)> quote(String provider, {DateTime? deadline, Future<void>? cancelled}) — Reads [provider]’s catalogue with unchecked availability; nothing starts or is renewed.
  • Future<(ServerQuote?, ServerFailure?)> checkOffer(String provider, ServerOffer offer, { DateTime? deadline, Future<void>? cancelled, }) — Checks only [offer]’s GPU class and uniquely matches its id and priority; nothing starts or is renewed.
  • Future<ServerSession> deploy(ServerQuote quote, ServerOffer offer, int idleMinutes, {String? engine, String? stack}) — Starts one server of [offer] from [quote], with a lease of [idleMinutes]; answers its session.
  • Future<ServerSession> stop(String name) — Asks [name]’s provider to stop it; the session says stopping until its provider says it stopped.
  • ServerHold? hold(RenderDestination destination) — A job’s claim on [destination]’s lease, renewed while the claim is held; null for a destination of no session.
  • bool isHeld(String name) — Whether a job holds [name]’s lease now.
  • static const keptFinished — How many finished sessions each start keeps, the newest: the journal and the GPU page are cut back to them.
  • Future<void> restore() — Reads what the last run left and asks each provider what it has now: a deployment that was being asked is looked for by its name, and a server a provider lists that no session holds is found.
  • Future<void> check([String? provider, String reason = 'check']) — Asks each provider — or [provider] alone — for the servers it has, and brings the sessions to what it says; [reason] is why, for the log: start, tick, pluginOn, deploy, renew, or check; pluginOn also for…
  • Future<void> tick() — One round of looking after the servers: a start or a held server’s lease renewed before it runs out, and a provider asked about the servers that are starting, stopping or past their lease.
  • void start() — Starts looking after the servers every [tickEvery].
  • Future<void> close() — Stops looking after them; each keeps its lease, which its provider’s schedule is to enforce.

lib/src/source_composition.dart

• class ContentHash — A caller-computed content digest with its algorithm named, never computed by render.
  • ContentHash({required this.algorithm, required this.value}) — Captures nonempty hash facts without a digest library or source access.
  • final String algorithm — The caller’s named digest algorithm, retained without assuming a particular algorithm.
  • final String value — The digest supplied by the caller for exactly this frozen source content.
• class SourceSnapshot — One exact picked source version, its filename epoch and caller-supplied content hash.
  • SourceSnapshot({required this.pickedVersionStem, required this.contentHash}) — Derives entity and epoch from an exact bare version stem, refusing paths, extensions and pointers.
  • final String pickedVersionStem — The complete version stem that RenderRequest.source retains, including author and version.
  • final ContentHash contentHash — The content digest frozen by the caller before submission.
  • String get entityStem — The logical entity identity shared across epochs and versions, as VersionStem.groupKey defines it.
  • String? get epoch — The exact filename epoch, absent only for a type without that filename axis.
  • int get pickedVersion — The version number of the exact picked stem, without performing a new pick or resolution.
  • Map<String, Object?> toJson() — The exact source identity and caller’s digest as a request’s provenance holds them.
  • static SourceSnapshot? fromJson(Object? json) — Reads complete source provenance, refusing a malformed stem or absent hash facts.
• class RenderComposition — The frozen primary and dependency provenance with the prompt and structured JSON references.
  • RenderComposition({ required this.primary, List<SourceSnapshot> dependencies = const [], required this.prompt, Map<String, Object?> inputs = const… — Copies dependency snapshots and recursively freezes inputs when composition is captured (§6.15).
  • final SourceSnapshot primary — The primary source snapshot and its caller-supplied content hash.
  • final List<SourceSnapshot> dependencies — The exact dependency snapshots and their hashes, retained without later re-resolution.
  • final String prompt — The composed prompt, applied once and retained verbatim at submission.
  • final Map<String, Object?> inputs — Structured reference strings and maps in the same frozen JSON shape as RenderRequest.inputs.
  • String get source — The primary picked version’s full stem, which RenderRequest.source names.
• class OutfitRenderComposer — An outfit sheet’s frozen character and outfit, in that order, at their exact filename epoch.
  • OutfitRenderComposer({required this.dependency, required this.parentPrompt, Map<String, Object?> parentInputs = const {}}) — Captures the picked character, its words and its inputs without later source access.
  • final SourceSnapshot dependency — The character’s exact picked version and caller-computed content hash.
  • final String parentPrompt — The character’s captured positive prompt, before the outfit’s words.
  • final Map<String, Object?> parentInputs — The character’s frozen reference inputs, before the outfit’s references.
  • static Entity? resolveParent(FilmProject project, VersionStem outfit, Author? viewer) — Picks the parent character only at the outfit’s filename epoch, without creating an index entry (§9.2).
  • RenderComposition compose({required SourceSnapshot primary, required String prompt, Map<String, Object?> inputs = const {}}) — Joins the exact parent and outfit’s words with a blank line and their references without truncation.