@rslsp1/fa-app-tools 7.2.0 → 7.4.0

package/dist/szenen.d.ts

@@ -124,6 +124,59 @@ declare const SZENEN_EVENT_TYPES: {
      * wird mit `collectImageBatches` (`imageBatchStore.ts`).
      */
     readonly imageBatchPersisted: "szenen.image_batch_persisted";
+    /**
+     * Ein vorbereiteter Promptvorgang — der Durchstich „Szene → ChatGPT → Lauf".
+     *
+     * Der bestehende Promptpfad ruft das Modell selbst
+     * (`runPromptDerivation()`); ein aufrufendes Chatmodell formuliert dagegen
+     * **zwischen** zwei Werkzeugaufrufen. Damit zerfaellt der eine Vorgang in
+     * zwei, und der zweite braucht genau den Stand, den der erste eingefroren
+     * hat — sonst loeste der Abschluss die inzwischen geaenderte Szene neu auf
+     * und der Lauf behauptete eine Herkunft, die er nicht hat (D-22).
+     *
+     * Deshalb ein eigenes Ereignis und **kein** fluechtiger Prozesszustand: Der
+     * Snapshot ueberlebt Neustart, Hostwechsel und Sitzungsende, weil er im
+     * selben autoritativen Log liegt wie der Lauf, der daraus entsteht.
+     *
+     * Der Elementreducer ignoriert diesen Typ (`default:`-Zweig); gelesen wird
+     * mit `collectPromptOperations` (`scenePromptOperation.ts`).
+     */
+    readonly promptOperationPrepared: "szenen.prompt_operation_prepared";
+    /**
+     * Ein Bildauftrag wartet auf einen ausfuehrenden Flow-Host.
+     *
+     * Die vorhandene Auftragshistorie (`imageGenerationStarted`) beginnt
+     * **unmittelbar vor** dem Provideraufruf und kennt deshalb keinen wartenden
+     * Auftrag. Genau der entsteht hier: Ein Chatmodell beauftragt ueber MCP ein
+     * Bild, der Auftrag wird dauerhaft abgelegt, und der Werkzeugaufruf endet
+     * sofort mit seiner Kennung — er haelt keine Antwort minutenlang offen.
+     *
+     * Traegt **keinen** Prompt: Der steht im referenzierten Lauf, und ihn hier
+     * zu kopieren waere eine zweite Wahrheit ueber denselben eingefrorenen Text
+     * (D-103).
+     */
+    readonly imageJobRequested: "szenen.image_job_requested";
+    /**
+     * Ein Flow-Host beansprucht einen wartenden Bildauftrag.
+     *
+     * Ein append-only Log kennt kein Lock: Zwei Tabs koennen beide anhaengen.
+     * Deshalb ist die Uebernahme **nicht** der Append, sondern das Ergebnis
+     * einer deterministischen Schiedsregel darueber (`winningClaimOf`) — der
+     * erste Anspruch in Logreihenfolge gewinnt, und jeder Host liest nach
+     * seinem Append erneut, bevor er einen bezahlten Provideraufruf startet.
+     * Ein unterlegener Anspruch bleibt sichtbar stehen; er wird nicht geloescht,
+     * weil das Log das nicht kann und weil der Versuch ein Beleg ist.
+     */
+    readonly imageJobClaimed: "szenen.image_job_claimed";
+    /**
+     * Der Bildauftrag ist erledigt — mit dem Ausgang, den der Host gesehen hat.
+     *
+     * Getrennt von `imageGenerationFinished`: Jenes gehoert zum bezahlten
+     * Provideraufruf, dieses zur Zustellung. Ein Auftrag kann fehlschlagen,
+     * **bevor** ein Provider gerufen wurde (abgelehntes Profil), und dann gibt
+     * es kein `imageGenerationFinished`, das den Wartenden erloesen wuerde.
+     */
+    readonly imageJobSettled: "szenen.image_job_settled";
 };
 /** Ein einzelnes Bild innerhalb von `ImageBatchPersistedPayload` (D-6.9.2-6). */
 interface ImageBatchPersistedImage {
@@ -1915,6 +1968,35 @@ declare const UNCHECKED_PUBLISH_RULES: readonly string[];
  */
 declare function createHfElementStore(options: CreateHfElementStoreOptions): AuthoritativeSzenenStore & ChainQueries;
 
+/**
+ * Der HF-Kanal kann mehr als der hostneutrale `ElementEventChannel`: Er kann
+ * seinen Kopf-Commit nennen und gegen ihn schreiben.
+ *
+ * Das ist **keine** Erweiterung des allgemeinen Vertrags. Ein Kanal ohne
+ * Versionsbegriff — der Dateilog, der Speicherkanal — kann das nicht, und
+ * fordern darf es deshalb nur, wer es wirklich braucht: die exklusive
+ * Auftragsuebernahme (Kette `szenen-mcp-chatgpt-flow`).
+ */
+interface RevisionAwareEventChannel extends ElementEventChannel {
+    /** Der aktuelle Kopf-Commit des Bestands. */
+    readHead(): Promise<string>;
+    /**
+     * Die Ereignisse **bei genau dieser Revision**.
+     *
+     * Der Unterschied zu `readEvents()` ist die Dateiliste: Sie wird an die
+     * Revision gebunden, statt „irgendwann waehrend der Anfrage" zu gelten. Nur
+     * damit passt der gelesene Stand zu dem `parentCommit`, gegen den danach
+     * geschrieben wird — sonst koennte die Liste ein Ereignis uebersehen, das
+     * beim Kopf schon da war, und der Schreibvorgang ginge trotzdem durch.
+     */
+    readEventsAt(revision: string): Promise<readonly ElementEvent[]>;
+    /**
+     * Anhaengen, aber nur wenn der Bestand noch auf `parentCommit` steht.
+     *
+     * Wirft `HfPreconditionFailedError`, wenn nicht — und schreibt dann nichts.
+     */
+    appendEventAt(type: string, payload: unknown, parentCommit: string): Promise<void>;
+}
 interface CreateHfEventChannelOptions {
     /** HF-Namespace mit abschließendem Schrägstrich, wie in `hfStateService`. */
     namespace: string;
@@ -1945,7 +2027,7 @@ interface CreateHfEventChannelOptions {
  * Erfordert nur einen HF-Token — kein Server, keine Datenbank. Das ist die
  * Zusage von R-2 für Flow-FA Pure.
  */
-declare function createHfEventChannel(options: CreateHfEventChannelOptions): ElementEventChannel;
+declare function createHfEventChannel(options: CreateHfEventChannelOptions): RevisionAwareEventChannel;
 
 interface InMemoryEventChannel extends ElementEventChannel {
     /** Der rohe Log, für Prüfungen. */
@@ -2372,6 +2454,190 @@ interface CreateImageGenerationPortOptions {
 /** Der gemeinsame Bildgenerierungs-Port. */
 declare function createImageGenerationPort(options: CreateImageGenerationPortOptions): SzenenImageGenerationPort;
 
+/** Nutzlast von `imageJobRequested` — geschrieben beim MCP-Auftrag. */
+interface ImageJobRequestedPayload {
+    job_id: string;
+    prompt_run_id: string;
+    /** Das Zielmodell, mit dem ausgefuehrt werden soll — ausdruecklich (D-131). */
+    execution_target_model_key: string;
+    /** Dessen Ausfuehrungsprofil; die Faehigkeiten kommen von dort, nicht vom MCP. */
+    execution_profile_id: string;
+    image_count: number;
+    aspect_ratio?: string;
+    /** Wer beauftragt hat — der kanonische Nutzerschluessel des Aufrufers. */
+    requested_by: string;
+    /**
+     * Die Kennung des Bestands, in dem dieser Auftrag gilt — `hf:<namespace>`
+     * bzw. `file:<verzeichnis>`, dieselbe Form, an der die Projektionsschranke
+     * misst.
+     *
+     * Ein Auftrag ist an Nutzer **und** Bestand gebunden. Ein Host auf einem
+     * anderen Bestand sieht ihn gar nicht erst; einer, der ihn doch faende,
+     * schriebe sein Ergebnis dorthin, wo der Auftraggeber nicht sucht.
+     */
+    store_id: string;
+    created_at: string;
+}
+/** Nutzlast von `imageJobClaimed` — der Anspruch eines Flow-Hosts. */
+interface ImageJobClaimedPayload {
+    job_id: string;
+    claim_id: string;
+    /** Der Client, der beansprucht — zwei Tabs sind zwei Clients. */
+    client_id: string;
+    claimed_at: string;
+}
+/** Nutzlast von `imageJobSettled` — der Ausgang der Zustellung. */
+interface ImageJobSettledPayload {
+    job_id: string;
+    claim_id: string;
+    status: 'succeeded' | 'partial' | 'failed' | 'rejected';
+    /** Der Batch des bezahlten Aufrufs, sofern einer entstand. */
+    generation_batch_id?: string;
+    /** Das Library-Item des Batches, sofern eines entstand. */
+    item_id?: string;
+    produced_count?: number;
+    diagnostic?: string;
+    settled_at: string;
+}
+/**
+ * Der Auftrag, wie ein Leser ihn sieht.
+ *
+ * `claimed` heisst „ein Host fuehrt aus **oder** ist dabei abgebrochen" — aus
+ * dem Log allein ist das nicht unterscheidbar, genau wie bei `started` in
+ * `ImageGenerationOrder`. Das ist Absicht und kein Mangel: Ein Zustand, der
+ * beides trennte, muesste eine Lebendigkeit behaupten, die niemand belegt.
+ */
+interface ImageJob {
+    job_id: string;
+    prompt_run_id: string;
+    execution_target_model_key: string;
+    execution_profile_id: string;
+    image_count: number;
+    aspect_ratio?: string;
+    requested_by: string;
+    store_id: string;
+    created_at: string;
+    status: 'pending' | 'claimed' | 'succeeded' | 'partial' | 'failed' | 'rejected';
+    /** Der massgebliche Anspruch — der erste in Logreihenfolge. */
+    claim?: ImageJobClaimedPayload;
+    /** Alle Anspruechenden, auch die unterlegenen. Ein Versuch ist ein Beleg. */
+    claim_attempts: readonly ImageJobClaimedPayload[];
+    generation_batch_id?: string;
+    item_id?: string;
+    produced_count?: number;
+    diagnostic?: string;
+    settled_at?: string;
+}
+/**
+ * Liest alle Bildauftraege aus dem Ereignislog.
+ *
+ * Drei Durchgaenge in fester Reihenfolge — Auftrag, Anspruch, Abschluss —,
+ * damit ein Ereignis nie einen Auftrag erfindet, den es nicht gibt: Ein
+ * Anspruch oder Abschluss ohne `requested` wird ignoriert, genauso wie
+ * `collectImageGenerationOrders` ein `finished` ohne `started` ignoriert.
+ */
+declare function collectImageJobs(events: readonly ElementEvent[]): readonly ImageJob[];
+/** Alle Auftraege eines Prompt-Laufs, in Erfassungsreihenfolge. */
+declare function jobsForPromptRun(events: readonly ElementEvent[], runId: string): readonly ImageJob[];
+/** Ein einzelner Auftrag, oder `null`. */
+declare function findImageJob(events: readonly ElementEvent[], jobId: string): ImageJob | null;
+/**
+ * Ob dieser Anspruch der massgebliche ist.
+ *
+ * Die eine Frage, die ein Flow-Host nach seinem Append stellen muss, bevor er
+ * einen bezahlten Aufruf startet.
+ */
+declare function claimWon(job: ImageJob | null, claimId: string): boolean;
+/**
+ * Die Kennung des Bild-Batches eines Auftrags.
+ *
+ * **Aus der Auftragskennung abgeleitet und nicht gewuerfelt.** Damit ist ein
+ * zweiter Ausfuehrungsversuch desselben Auftrags auch dann noch harmlos, wenn
+ * er die Schiedsregel umginge: `collectImageGenerationOrders` haelt das erste
+ * `started` je `generation_batch_id` fest und ignoriert jedes weitere. Zwei
+ * unabhaengige Sicherungen fuer denselben teuren Fehler sind hier
+ * angemessen — der Schaden ist bezahlte Rechenzeit, nicht ein Logeintrag.
+ */
+declare function generationBatchIdOf(jobId: string): string;
+
+/**
+ * Was der Auftragskanal braucht.
+ *
+ * `readHead`, `readEventsAt` und `appendEventAt` sind **Pflicht**, nicht
+ * optional: Ohne sie gibt es keine verbindliche Uebernahme, und ein Host, der
+ * sie nicht hat, darf einen bezahlten Auftrag nicht uebernehmen. Ein
+ * optionaler Rueckfall auf blosses `appendEvent` waere genau die Fassung, die
+ * zwei Clients beide gewinnen liess.
+ */
+interface ImageJobChannel {
+    readEvents(): Promise<readonly ElementEvent[]>;
+    /**
+     * Der schlichte Anhang — fuer den **Abschluss**.
+     *
+     * Er braucht kein CAS: Nur der Gewinner schreibt ihn, und die Faltung
+     * akzeptiert ohnehin nur den Abschluss des massgeblichen Anspruchs.
+     */
+    appendEvent(type: string, payload: unknown): Promise<void>;
+    /** Der aktuelle Kopf-Commit des Bestands. */
+    readHead(): Promise<string>;
+    /** Die Ereignisse bei genau dieser Revision — die Liste ist daran gebunden. */
+    readEventsAt(revision: string): Promise<readonly ElementEvent[]>;
+    /** Anhaengen, aber nur wenn der Bestand noch auf `parentCommit` steht. */
+    appendEventAt(type: string, payload: unknown, parentCommit: string): Promise<void>;
+}
+/** Die Ausgaenge einer Uebernahme. */
+type ClaimAndRunResult = 
+/** Uebernommen und ausgefuehrt — der Ausgang steht im Auftrag. */
+{
+    kind: 'ok';
+    job: ImageJob;
+}
+/**
+ * Ein anderer Client hat den Auftrag. **Kein Fehler**: Genau dafuer gibt es
+ * die Schiedsregel, und dieser Client hat nichts bezahlt.
+ */
+ | {
+    kind: 'lost';
+    job: ImageJob;
+    message: string;
+}
+/** Fachlich abgelehnt — falscher Zustand, falscher Bestand, kein Auftrag. */
+ | {
+    kind: 'rejected';
+    message: string;
+}
+/** Technisch gescheitert; der Bestand ist in Ordnung, der Zugriff nicht. */
+ | {
+    kind: 'error';
+    message: string;
+    retryable: boolean;
+};
+interface SzenenImageJobPort {
+    /** Die Auftraege eines Prompt-Laufs, aus dem autoritativen Log. */
+    listJobs(runId: string): Promise<QueryResult<readonly ImageJob[]>>;
+    /** Beansprucht einen wartenden Auftrag und fuehrt ihn als Gewinner aus. */
+    claimAndRun(jobId: string): Promise<ClaimAndRunResult>;
+}
+interface CreateImageJobPortOptions {
+    channel: ImageJobChannel;
+    /** Der bestehende Bildgenerierungs-Port dieses Hosts (D-116/D-119). */
+    imageGeneration: SzenenImageGenerationPort;
+    /**
+     * Die Bestandskennung dieses Hosts — `hf:<namespace>`.
+     *
+     * Sie wird gegen die des Auftrags geprueft. Nutzer, Umgebung und Bestand
+     * muessen zusammenpassen; ein Host, der einen fremden Auftrag ausfuehrte,
+     * schriebe sein Ergebnis in einen Bestand, in dem es niemand sucht.
+     */
+    storeId: string;
+    /** Diese Sitzung. Zwei Tabs sind zwei Clients — sonst sind sie ununterscheidbar. */
+    clientId: string;
+    newClaimId?: () => string;
+    now?: () => Date;
+}
+/** Der Uebernahmeweg als Port. */
+declare function createImageJobPort(options: CreateImageJobPortOptions): SzenenImageJobPort;
+
 /** Eine benannte Seedliste, wie der Nutzer sie im Dropdown sieht. */
 interface SeedVorlage {
     /** Fehlt bei der eingebauten Vorlage — sie liegt in keinem Speicher. */
@@ -3178,6 +3444,16 @@ interface SzenenViewPort {
      * Bildlauf starten und das Ergebnis danach verlieren.
      */
     imageGeneration?: SzenenImageGenerationPort;
+    /**
+     * Bildauftraege aus dem Chat uebernehmen — fehlt, wo es nichts auszufuehren
+     * gibt.
+     *
+     * Haengt an denselben zwei Voraussetzungen wie `imageGeneration`: ohne
+     * Provider und ohne kanonischen Schreibweg darf ein Host keinen bezahlten
+     * Auftrag uebernehmen (D-122). Zusaetzlich braucht er den autoritativen
+     * Kanal, denn die Uebernahme ist ein Append mit Gegenlesen.
+     */
+    imageJobs?: SzenenImageJobPort;
 }
 /**
  * Die Fähigkeiten eines Ports, wie die View sie abfragt.
@@ -3198,6 +3474,8 @@ interface SzenenViewCapabilities {
     imageOrderHistory: boolean;
     imageBatchWrite: boolean;
     imageGeneration: boolean;
+    /** Bildauftraege aus dem Chat uebernehmen (Kette szenen-mcp-chatgpt-flow). */
+    imageJobs: boolean;
 }
 declare function capabilitiesOf(port: SzenenViewPort): SzenenViewCapabilities;
 /**
@@ -3332,6 +3610,42 @@ interface GruppierbaresBild extends LibraryImage {
  * Locator-Position aufsteigend; die ist stabil, der Zeitstempel wäre es nicht.
  */
 declare function gruppiereZuItems(bilder: readonly GruppierbaresBild[]): readonly LibraryImageItem[];
+/** Ein Galerieeintrag, wie ihn `metadata.gallery` einer Library-Zeile fuehrt. */
+interface BestandsGalerieEintrag {
+    file?: string | null;
+}
+/** Eine Library-Zeile, wie sie `/api/storage/:user/library` ausliefert. */
+interface BestandsItem {
+    id: string;
+    title?: string | null;
+    timestamp?: number | null;
+    gallery?: readonly BestandsGalerieEintrag[] | null;
+}
+/**
+ * Der Locator eines Bildes — dieselbe Bildung wie `locatorVon()` auf dem
+ * Server und beim Hochladen nach HF: bei einem Bild die blosse Kennung, bei
+ * mehreren `${id}-${position}`. `locatorTeile` oben zerlegt genau das wieder.
+ */
+declare function locatorAus(itemId: string, position: number, anzahl: number): string;
+/** Der MIME-Typ aus der Dateiendung — dieselben drei Faelle wie serverseitig. */
+declare function mimeTypAus(dateiname: string): string;
+/**
+ * Library-Zeilen → Werke fuer den Bildwaehler.
+ *
+ * @param items   Der Bestand, wie ihn der Library-Lesepfad liefert.
+ * @param options `search` filtert am Titel, `limit` zaehlt **Werke** (nicht
+ *                Bilder), `thumbUrl` bildet die Vorschauquelle aus dem
+ *                Dateinamen — der Host reicht sie herein, damit diese Funktion
+ *                keine Adresse kennt.
+ *
+ * Ein Item ohne lesbaren Galerieeintrag ist kein leeres Werk, sondern gar
+ * keins: eine Karte ohne Bild waere nur eine Sackgasse.
+ */
+declare function itemsAusBestand(items: readonly BestandsItem[], options?: {
+    search?: string;
+    limit?: number;
+    thumbUrl?: (dateiname: string) => string;
+}): readonly LibraryImageItem[];
 
 interface VorschauLauf {
     /** Wird `true`, sobald der Aufrufer das Ergebnis nicht mehr braucht. */
@@ -3554,6 +3868,17 @@ interface CreateFlowSzenenViewPortOptions {
     imageContextId?: () => string | null;
     /** Kennung je abgelegtem Batch-Bild. Ersetzbar, damit ein Test nicht würfelt. */
     newBatchImageId?: (generationBatchId: string, position: number) => string;
+    /**
+     * Diese Sitzung — die Kennung, mit der dieser Host einen Bildauftrag
+     * beansprucht (Kette `szenen-mcp-chatgpt-flow`).
+     *
+     * **Zwei Tabs müssen zwei Clients sein**, sonst kann die Schiedsregel den
+     * Doppelklick nicht vom zweiten Tab unterscheiden. Vorgabe ist deshalb eine
+     * frisch gezogene Kennung je Portinstanz, kein stabiler Gerätewert.
+     */
+    imageJobClientId?: string;
+    /** Anspruchskennung je Übernahme. Ersetzbar, damit ein Test nicht würfelt. */
+    newImageJobClaimId?: () => string;
 }
 /**
  * Complete Flow adapter for the shared SzenenView: authoritative HF elements
@@ -3895,6 +4220,164 @@ interface TargetModelChoices {
  */
 declare function selectableTargetModels(queries: VisibilityQueries, contextChain: readonly (string | null)[]): Promise<QueryResult<TargetModelChoices>>;
 
+/**
+ * Der Anbieter, der in einem so entstandenen Lauf steht.
+ *
+ * `mcp_client` und nicht `openai`/`chatgpt`: Was der Server sicher weiss, ist
+ * dass **sein MCP-Aufrufer** formuliert hat. Welcher Anbieter dahinter steht,
+ * sagt ihm niemand — und ein geratener Anbietername waere im Lauf spaeter
+ * nicht mehr von einem belegten zu unterscheiden (D-107).
+ */
+declare const MCP_CLIENT_PROVIDER = "mcp_client";
+/**
+ * Die Modellkennung, wenn der Host keine belegte liefert — und das tut er nie.
+ *
+ * Bewusst ein sprechender Platzhalter statt einer Modellversion: `model_id`
+ * ist das Feld, an dem ein Leser ablesen soll, **womit** formuliert wurde.
+ * Eine dort eingetragene Selbstauskunft saehe aus wie eine belegte Kennung.
+ * Die Selbstauskunft steht deshalb in `execution_origin.declared_model_id` und
+ * traegt dort sichtbar, dass sie unbelegt ist.
+ */
+declare const UNVERIFIED_MODEL_ID = "mcp-client-unspecified";
+/**
+ * Die Herkunft der Ausfuehrung, so ehrlich wie sie belegbar ist.
+ *
+ * Additiv am Lauf und nicht in `model_id`/`provider` versteckt: Der
+ * Unterschied zwischen „das war Modell X" und „der Aufrufer sagt, es war
+ * Modell X" ist genau der, um den es geht.
+ */
+interface PromptExecutionOrigin {
+    /** Wer den Lauf eingereicht hat — hier immer der MCP-Werkzeugweg. */
+    host: 'mcp';
+    /** Was der Aufrufer ueber sich selbst gesagt hat, unveraendert und unbelegt. */
+    declared_model_id?: string;
+    /**
+     * Ob die unten mitgegebene Renderer-Anweisung die tatsaechliche
+     * Systemnachricht des formulierenden Chats war.
+     *
+     * Sie war es nie: Der MCP reicht sie als Werkzeugergebnis heraus; was im
+     * Chat als Systemprompt stand, kennt der Server nicht. Das Feld steht
+     * trotzdem im Lauf, weil `system_prompt` sonst genau so gelesen wuerde.
+     */
+    renderer_instruction_was_system_prompt: false;
+}
+/** Der Antwortvertrag, den der Aufrufer erfuellen muss — maschinenlesbar. */
+interface PromptResponseContract {
+    format: 'json';
+    /** Pflichtfelder der Antwort, wie `checkRunResponse()` sie prueft. */
+    required_fields: readonly string[];
+    /** Ob ein Negativ-Prompt zugesagt ist (sonst muss `negative` null bleiben). */
+    negative_prompt_allowed: boolean;
+    /** Jeder dieser Knoten muss in `visibility.nodes` erscheinen (D-21). */
+    node_ids: readonly string[];
+    /** Die Sprache, in der `positive` formuliert wird. */
+    prompt_language: string;
+}
+/** Ein vorbereiteter Promptvorgang — dauerhaft unter `operation_id`. */
+interface PreparedPromptOperation {
+    operation_id: string;
+    /** Die eingefrorene Szene: genau ein Entwurfs- oder Versionsstand (D-135). */
+    scene: FrozenSceneState;
+    context_id: string | null;
+    /** Die Arbeitsanweisung des Nutzers, soweit eine gegeben wurde. */
+    user_instruction: string | null;
+    /** Der eingefrorene `RendererInput` — woertlich der des bestehenden Pfads. */
+    renderer_input: RendererInput;
+    /**
+     * Die Renderer-Anweisung (`buildSystemInstruction`).
+     *
+     * Sie ist **Material fuer den Aufrufer**, nicht sein Systemprompt. Beim
+     * Abschluss landet sie unveraendert in `system_prompt` des Laufs, weil das
+     * Feld seit Stufe 3 genau diese Anweisung fuehrt.
+     */
+    renderer_instruction: string;
+    /** Die Nutzernachricht: die Renderer-Eingabe als JSON (D-47). */
+    renderer_payload: string;
+    response_contract: PromptResponseContract;
+    prepared_by: string;
+    created_at: string;
+}
+/** Nutzlast von `promptOperationPrepared`. */
+type PromptOperationPreparedPayload = PreparedPromptOperation;
+/** Liest alle vorbereiteten Vorgaenge aus dem Ereignislog. */
+declare function collectPromptOperations(events: readonly ElementEvent[]): readonly PreparedPromptOperation[];
+/** Ein einzelner vorbereiteter Vorgang, oder `null`. */
+declare function findPromptOperation(events: readonly ElementEvent[], operationId: string): PreparedPromptOperation | null;
+interface PreparePromptOperationInput {
+    sceneElementId: string;
+    operationId: string;
+    store: ChainQueries;
+    resolver: ReferenceResolver;
+    contextChain: readonly (string | null)[];
+    contextId: string | null;
+    userInstruction?: string | null;
+    preparedBy: string;
+    now?: () => Date;
+}
+type PreparePromptOperationResult = {
+    kind: 'ok';
+    operation: PreparedPromptOperation;
+} | FreezeFailure;
+/**
+ * Friert den Arbeitsstand einer Szene ein und baut daraus den Vorgang.
+ *
+ * Ruft **kein** Modell — hier entstehen keine Kosten. Das Einfrieren ist
+ * woertlich `freezeSceneWorkingState()`, also derselbe Zwei-Durchgang-Vergleich
+ * mit denselben drei Ausgaengen wie im bestehenden Pfad (D-97/D-135). Ein
+ * Konflikt bleibt ein Konflikt, kein „nochmal versuchen".
+ */
+declare function preparePromptOperation(input: PreparePromptOperationInput): Promise<PreparePromptOperationResult>;
+/**
+ * Der Antwortvertrag, abgelesen an derselben Eingabe wie die Anweisung.
+ *
+ * Bewusst abgelesen und nicht danebengeschrieben: Was `checkRunResponse()
+ * prueft, entscheidet allein `promptRun.ts`. Ein hier gepflegter zweiter
+ * Katalog liefe irgendwann auseinander, und der Aufrufer bekaeme einen
+ * Vertrag, den die Pruefung nicht kennt.
+ */
+declare function responseContractOf(input: RendererInput): PromptResponseContract;
+interface CompletePromptOperationInput {
+    operation: PreparedPromptOperation;
+    /** Die Antwort des aufrufenden Modells, woertlich. */
+    response: string;
+    runId: string;
+    /** Was der Aufrufer ueber sein eigenes Modell sagt — unbelegt (D-107). */
+    declaredModelId?: string | null;
+    now?: () => Date;
+}
+type CompletePromptOperationResult = {
+    kind: 'ok';
+    record: PromptRunRecord;
+} | {
+    kind: 'rejected';
+    message: string;
+};
+/**
+ * Macht aus der Antwort des Aufrufers einen normalen Promptlauf.
+ *
+ * **Eine ungueltige Antwort wird nicht als gescheiterter Lauf abgelegt.** Das
+ * ist der eine bewusste Unterschied zum Providerpfad, und er hat einen Grund:
+ * Dort belegt ein `failed` einen **bezahlten** Aufruf, der sich nicht
+ * wiederholen laesst, ohne noch einmal zu kosten (D-23 §6). Hier hat niemand
+ * bezahlt — der Aufrufer hat nur falsch formuliert und kann es unter derselben
+ * `operation_id` sofort richtig tun. Ein Fehlerlauf waere hier kein Nachweis,
+ * sondern Muell im autoritativen Bestand, und er wuerde die Wiederholung
+ * ausserdem als Konflikt blockieren.
+ */
+declare function completePromptOperation(input: CompletePromptOperationInput): CompletePromptOperationResult;
+/**
+ * Der Lauf, der aus diesem Vorgang schon entstanden ist — oder `null`.
+ *
+ * Grundlage der Idempotenz: Derselbe Vorgang mit derselben Antwort liefert
+ * denselben Lauf; eine **andere** Antwort unter derselben Kennung ist ein
+ * Konflikt und kein zweiter Lauf. Verglichen wird die woertliche Antwort aus
+ * `raw_output` — es braucht keinen Fingerabdruck neben etwas, das der Lauf
+ * ohnehin vollstaendig traegt.
+ */
+declare function runOfOperation(runs: readonly PromptRunRecord[], operationId: string): PromptRunRecord | null;
+/** Ob eine eingereichte Antwort woertlich die des bereits gespeicherten Laufs ist. */
+declare function sameResponseAs(run: PromptRunRecord, response: string): boolean;
+
 interface CreateHfImageBatchPersistenceOptions {
     namespace: string;
     token: string;
@@ -4055,4 +4538,4 @@ interface SzenenViewProps {
 }
 declare const SzenenView: React__default.FC<SzenenViewProps>;
 
-export { type AttachLibraryItemInput, type AttachLibraryItemResult, AuthoritativeSzenenStore, CATALOGUE_TYPES, CapabilityAnchorError, type CapabilityFlag, type CapabilityFlagName, type CapabilityReason, type CapabilityReport, type CapabilityReportInput, type CapabilityScope, type CapabilityState, type ChainQueries, type ClientDerivationChannel, type ClientDerivationStore, ContextChainPort, type CreateBrowserTextGenerationPortOptions, type CreateClientDerivationPortOptions, type CreateClientRunPortOptions, type CreateFlowSzenenViewPortOptions, type CreateHfElementStoreOptions, type CreateHfEventChannelOptions, type CreateHfImageBatchHistoryOptions, type CreateHfImageBatchPersistenceOptions, type CreateImageGenerationPortOptions, type CreateMemoryViewPortOptions, DEFAULT_SEED_VORLAGE, DerivableType, DerivationAssessment, DerivationConflict, DerivationDiagnostic, DerivationFailure, DerivationImage, DerivationInputMode, type DeriveItemInput, type DerivedItem, type DerivedLineage, type DerivedRelationship, type DerivedSzenenReference, type DifferentialResult, type DifferentialStep, type Divergence, DraftChainMeta, ELEMENT_VERSION_SCHEMA_FILE, type ElementEvent, type ElementEventChannel, ElementSnapshot, type ElementStoreState, type ExecutableImageModel, type ExecutionTargetModel, type ExistingSzenenItem, FLOW_EXECUTION_PATH, type FlowGenerateImage, type FlowGenerateImageParams, FlowGenerateText, type FreezeDraftChainInput, type FreezeFailure, type FreezeResult, type FreezeSceneResult, type FreezeSceneSuccess, type FreezeSceneWorkingStateInput, type FreezeSuccess, type FrozenChainNode, type FrozenSceneState, type GeneratedImage, type GruppierbaresBild, type HfImageStore, type HfImageStoreOptions, type IdFactory, type ImageBatchPersistedImage, type ImageBatchPersistedPayload, type ImageExecutionProfile, type ImageExecutionRoute, type ImageExecutionTargetModelReader, type ImageGenerationBatchPersistence, type ImageGenerationEventChannel, type ImageGenerationFinishedPayload, type ImageGenerationOrder, type ImageGenerationProviderPort, type ImageGenerationResult, type ImageGenerationRunReader, type ImageGenerationStartedPayload, type ImageHostCapability, type ImageModelChoice, type ImageModelParameters, ImageProvenance, type ImageProviderInput, type ImportBatchImageInput, type ImportBatchInput, type InMemoryEventChannel, type InputError, type IntegrityVerdict, type ItemDerivationFailure, type ItemDerivationFailureClass, type ItemDerivationResult, type ItemMedium, type LibraryImage, type LibraryImageItem, type NodeContribution, NotDerivable, type Notice, type NoticeTone, PROMPT_RULE_EFFECT, type PromptBatchImageRef, type PromptBatchOrigin, type PromptDiagnostic, type PromptEffect, type PromptImageBatch, type PromptRunOutcome, type PromptRunOutput, type PromptRunPersistencePort, type PromptRunRecord, type PromptRunRecordedPayload, type ProviderCheckRecord, type ProviderCheckRecordedPayload, type ProviderCheckResult, PublishCheckResult, PublishFinding, RULES_WITHOUT_CAPABILITY_EFFECT, RULE_SCOPES, type RawSchema, type RecordedDerivationInput, type RecordedProposal, type RecoveryStatus, type ReducerFinding, ReferenceResolver, type RendererInput, type ResolveFailure, type ResolveResult, type ResolveScenePayloadInput, type ResolveShotInput, type ResolveShotPayloadInput, ResolveTechnicalError, type ResolvedCamera, type ResolvedNode, type ResolvedPlacement, type RunEventChannel, type RunFailure, type RunFailureClass, type RunItemReference, SZENEN_EVENT_PREFIX, SZENEN_EVENT_TYPES, SZENEN_ITEM_PREFIX, SZENEN_SCHEMAS, SZENEN_SNAPSHOT_FILE, SZENEN_SNAPSHOT_PREFIX, SZENEN_SNAPSHOT_SCHEMA_VERSION, type SaveRunAsItemInput, type SceneDerivationPersistencePort, type SceneDerivationRecord, type SceneDerivationRecordedPayload, type SceneDerivationRecoveryRecord, type SceneDerivationRecoveryRecordedPayload, SchemaError, type SeedVorlage, type SeedZuordnung, type SeedZuordnungEintrag, type SelectableTargetModel, type StartImageGenerationInput, type StartRunFromSceneInput, type StartRunInput, type StepState, type SzenenArea, type SzenenAreaId, type SzenenBatchOrigin, type SzenenBatchOriginFailure, type SzenenBatchOriginVerdict, type SzenenBatchSourceKind, SzenenCommands, SzenenElementStore, SzenenElementType, type SzenenImageBatchHistoryPort, type SzenenImageBatchWritePort, type SzenenImageGenerationPort as SzenenImageGenerationPortContract, type SzenenImageLibraryPort, type SzenenItemPort, type SzenenLeseErgebnis, type SzenenMediaPort, SzenenQueries, type SzenenRunPort, type SzenenSeedTemplatePort, type SzenenSnapshot, SzenenView, type SzenenViewCapabilities, type SzenenViewPort, type SzenenViewProps, TargetModelResolution, TextGenerationPort, UNCHECKED_PUBLISH_RULES, UPLOAD_MAX_BYTES, type UnselectableTargetModel, UnusableProposal, type VersionMedium, type VisibilityNode, type ZipBild, areasFor, batchesForPromptRun, bildPfad, buildSystemInstruction, buildSzenenSnapshot, buildUserPrompt, callOptional, capabilitiesOf, capabilityGate, capabilityReport, catalogueFor, checkCreateElementInput, checkElementType, checkImageExecutionProfile, checkImageExecutionProfiles, checkImageModelParameters, checkOptionalId, checkParents, checkPayloadPresent, checkPromptRunRecord, checkPublishVersionInput, checkRequiredId, checkReviseMetadataInput, checkRevision, checkRunResponse, checkSceneDerivationRecord, checkSceneDerivationRecoveryRecord, checkSetPreferredHeadInput, checkSzenenBatchOrigin, checkTitle, checkWriteDraftInput, collectImageBatches, collectImageGenerationOrders, collectPromptRuns, collectProviderChecks, collectSceneDerivationRecoveries, collectSceneDerivations, createBrowserTextGenerationPort, createClientDerivationPort, createClientRunPort, createEventLogDerivationPersistence, createEventLogRunPersistence, createFlowImageProvider, createFlowSzenenViewPort, createHfElementStore, createHfEventChannel, createHfImageBatchHistory, createHfImageBatchWrite, createHfImageGenerationBatchPersistence, createHfImageLibrary, createHfImageStore, createImageGenerationPort, createInMemoryEventChannel, createMemoryViewPort, derivationPoliciesOf, deriveItemFromRun, deriveLineage, describableContent, diagnosticOfFinding, diagnosticOfSchemaError, differentialSteps, draftRevisionOf, executableImageModels, findExecutableImageModel, findImageBatch, findImageGenerationOrder, findPromptRun, findProviderCheck, findSceneDerivation, findSceneDerivationRecovery, firstError, formatSeedListe, freezeDraftChain, freezeSceneWorkingState, gesamtHerkunft, gruppiereZuItems, hasPlacementCapability, isKnownElementType, isSzenenItemId, istSzenenSnapshotDatei, istZipDatei, itemIdForRun, ladeVorschauen, leseBilderAusZip, locatorTeile, logRevisionOf, mergeSnapshotAndPending, mergeSzenenBatchOrigin, mitDefaultVorlage, noticeFor, ordersForPromptRun, ordneSeedsZu, parseRunResponse, parseSeedListe, parseSzenenSnapshot, preferredHeadRevisionOf, promptDiagnosticsOf, publishedHeadsOf, recoveriesForRun, recoveryStatusOf, reduceElementEvents, resolveArea, resolveScenePayload, resolveShot, resolveShotPayload, roundOfRun, rulesWithoutPromptEffect, runPromptDerivation, runStoreDifferential, sceneOnlyCapabilities, scopeOfPath, seedFehlerText, selectableTargetModels, szenenSnapshotFilename, totalModelCalls, typAusBytes, unclassifiedPublishRules, unsupportedReason };
+export { type AttachLibraryItemInput, type AttachLibraryItemResult, AuthoritativeSzenenStore, type BestandsGalerieEintrag, type BestandsItem, CATALOGUE_TYPES, CapabilityAnchorError, type CapabilityFlag, type CapabilityFlagName, type CapabilityReason, type CapabilityReport, type CapabilityReportInput, type CapabilityScope, type CapabilityState, type ChainQueries, type ClaimAndRunResult, type ClientDerivationChannel, type ClientDerivationStore, type CompletePromptOperationInput, type CompletePromptOperationResult, ContextChainPort, type CreateBrowserTextGenerationPortOptions, type CreateClientDerivationPortOptions, type CreateClientRunPortOptions, type CreateFlowSzenenViewPortOptions, type CreateHfElementStoreOptions, type CreateHfEventChannelOptions, type CreateHfImageBatchHistoryOptions, type CreateHfImageBatchPersistenceOptions, type CreateImageGenerationPortOptions, type CreateImageJobPortOptions, type CreateMemoryViewPortOptions, DEFAULT_SEED_VORLAGE, DerivableType, DerivationAssessment, DerivationConflict, DerivationDiagnostic, DerivationFailure, DerivationImage, DerivationInputMode, type DeriveItemInput, type DerivedItem, type DerivedLineage, type DerivedRelationship, type DerivedSzenenReference, type DifferentialResult, type DifferentialStep, type Divergence, DraftChainMeta, ELEMENT_VERSION_SCHEMA_FILE, type ElementEvent, type ElementEventChannel, ElementSnapshot, type ElementStoreState, type ExecutableImageModel, type ExecutionTargetModel, type ExistingSzenenItem, FLOW_EXECUTION_PATH, type FlowGenerateImage, type FlowGenerateImageParams, FlowGenerateText, type FreezeDraftChainInput, type FreezeFailure, type FreezeResult, type FreezeSceneResult, type FreezeSceneSuccess, type FreezeSceneWorkingStateInput, type FreezeSuccess, type FrozenChainNode, type FrozenSceneState, type GeneratedImage, type GruppierbaresBild, type HfImageStore, type HfImageStoreOptions, type IdFactory, type ImageBatchPersistedImage, type ImageBatchPersistedPayload, type ImageExecutionProfile, type ImageExecutionRoute, type ImageExecutionTargetModelReader, type ImageGenerationBatchPersistence, type ImageGenerationEventChannel, type ImageGenerationFinishedPayload, type ImageGenerationOrder, type ImageGenerationProviderPort, type ImageGenerationResult, type ImageGenerationRunReader, type ImageGenerationStartedPayload, type ImageHostCapability, type ImageJob, type ImageJobChannel, type ImageJobClaimedPayload, type ImageJobRequestedPayload, type ImageJobSettledPayload, type ImageModelChoice, type ImageModelParameters, ImageProvenance, type ImageProviderInput, type ImportBatchImageInput, type ImportBatchInput, type InMemoryEventChannel, type InputError, type IntegrityVerdict, type ItemDerivationFailure, type ItemDerivationFailureClass, type ItemDerivationResult, type ItemMedium, type LibraryImage, type LibraryImageItem, MCP_CLIENT_PROVIDER, type NodeContribution, NotDerivable, type Notice, type NoticeTone, PROMPT_RULE_EFFECT, type PreparePromptOperationInput, type PreparePromptOperationResult, type PreparedPromptOperation, type PromptBatchImageRef, type PromptBatchOrigin, type PromptDiagnostic, type PromptEffect, type PromptExecutionOrigin, type PromptImageBatch, type PromptOperationPreparedPayload, type PromptResponseContract, type PromptRunOutcome, type PromptRunOutput, type PromptRunPersistencePort, type PromptRunRecord, type PromptRunRecordedPayload, type ProviderCheckRecord, type ProviderCheckRecordedPayload, type ProviderCheckResult, PublishCheckResult, PublishFinding, RULES_WITHOUT_CAPABILITY_EFFECT, RULE_SCOPES, type RawSchema, type RecordedDerivationInput, type RecordedProposal, type RecoveryStatus, type ReducerFinding, ReferenceResolver, type RendererInput, type ResolveFailure, type ResolveResult, type ResolveScenePayloadInput, type ResolveShotInput, type ResolveShotPayloadInput, ResolveTechnicalError, type ResolvedCamera, type ResolvedNode, type ResolvedPlacement, type RunEventChannel, type RunFailure, type RunFailureClass, type RunItemReference, SZENEN_EVENT_PREFIX, SZENEN_EVENT_TYPES, SZENEN_ITEM_PREFIX, SZENEN_SCHEMAS, SZENEN_SNAPSHOT_FILE, SZENEN_SNAPSHOT_PREFIX, SZENEN_SNAPSHOT_SCHEMA_VERSION, type SaveRunAsItemInput, type SceneDerivationPersistencePort, type SceneDerivationRecord, type SceneDerivationRecordedPayload, type SceneDerivationRecoveryRecord, type SceneDerivationRecoveryRecordedPayload, SchemaError, type SeedVorlage, type SeedZuordnung, type SeedZuordnungEintrag, type SelectableTargetModel, type StartImageGenerationInput, type StartRunFromSceneInput, type StartRunInput, type StepState, type SzenenArea, type SzenenAreaId, type SzenenBatchOrigin, type SzenenBatchOriginFailure, type SzenenBatchOriginVerdict, type SzenenBatchSourceKind, SzenenCommands, SzenenElementStore, SzenenElementType, type SzenenImageBatchHistoryPort, type SzenenImageBatchWritePort, type SzenenImageGenerationPort as SzenenImageGenerationPortContract, type SzenenImageJobPort, type SzenenImageLibraryPort, type SzenenItemPort, type SzenenLeseErgebnis, type SzenenMediaPort, SzenenQueries, type SzenenRunPort, type SzenenSeedTemplatePort, type SzenenSnapshot, SzenenView, type SzenenViewCapabilities, type SzenenViewPort, type SzenenViewProps, TargetModelResolution, TextGenerationPort, UNCHECKED_PUBLISH_RULES, UNVERIFIED_MODEL_ID, UPLOAD_MAX_BYTES, type UnselectableTargetModel, UnusableProposal, type VersionMedium, type VisibilityNode, type ZipBild, areasFor, batchesForPromptRun, bildPfad, buildSystemInstruction, buildSzenenSnapshot, buildUserPrompt, callOptional, capabilitiesOf, capabilityGate, capabilityReport, catalogueFor, checkCreateElementInput, checkElementType, checkImageExecutionProfile, checkImageExecutionProfiles, checkImageModelParameters, checkOptionalId, checkParents, checkPayloadPresent, checkPromptRunRecord, checkPublishVersionInput, checkRequiredId, checkReviseMetadataInput, checkRevision, checkRunResponse, checkSceneDerivationRecord, checkSceneDerivationRecoveryRecord, checkSetPreferredHeadInput, checkSzenenBatchOrigin, checkTitle, checkWriteDraftInput, claimWon, collectImageBatches, collectImageGenerationOrders, collectImageJobs, collectPromptOperations, collectPromptRuns, collectProviderChecks, collectSceneDerivationRecoveries, collectSceneDerivations, completePromptOperation, createBrowserTextGenerationPort, createClientDerivationPort, createClientRunPort, createEventLogDerivationPersistence, createEventLogRunPersistence, createFlowImageProvider, createFlowSzenenViewPort, createHfElementStore, createHfEventChannel, createHfImageBatchHistory, createHfImageBatchWrite, createHfImageGenerationBatchPersistence, createHfImageLibrary, createHfImageStore, createImageGenerationPort, createImageJobPort, createInMemoryEventChannel, createMemoryViewPort, derivationPoliciesOf, deriveItemFromRun, deriveLineage, describableContent, diagnosticOfFinding, diagnosticOfSchemaError, differentialSteps, draftRevisionOf, executableImageModels, findExecutableImageModel, findImageBatch, findImageGenerationOrder, findImageJob, findPromptOperation, findPromptRun, findProviderCheck, findSceneDerivation, findSceneDerivationRecovery, firstError, formatSeedListe, freezeDraftChain, freezeSceneWorkingState, generationBatchIdOf, gesamtHerkunft, gruppiereZuItems, hasPlacementCapability, isKnownElementType, isSzenenItemId, istSzenenSnapshotDatei, istZipDatei, itemIdForRun, itemsAusBestand, jobsForPromptRun, ladeVorschauen, leseBilderAusZip, locatorAus, locatorTeile, logRevisionOf, mergeSnapshotAndPending, mergeSzenenBatchOrigin, mimeTypAus, mitDefaultVorlage, noticeFor, ordersForPromptRun, ordneSeedsZu, parseRunResponse, parseSeedListe, parseSzenenSnapshot, preferredHeadRevisionOf, preparePromptOperation, promptDiagnosticsOf, publishedHeadsOf, recoveriesForRun, recoveryStatusOf, reduceElementEvents, resolveArea, resolveScenePayload, resolveShot, resolveShotPayload, responseContractOf, roundOfRun, rulesWithoutPromptEffect, runOfOperation, runPromptDerivation, runStoreDifferential, sameResponseAs, sceneOnlyCapabilities, scopeOfPath, seedFehlerText, selectableTargetModels, szenenSnapshotFilename, totalModelCalls, typAusBytes, unclassifiedPublishRules, unsupportedReason };