Docs

Leases

TL;DR

  • Ein lease ist ein Analogon zur Datenbanktransaktion für Cloud-Ressourcen. Öffne ein lease, stemple jede erstellte Ressource mit --lease <id>, dann schließe das lease mit commit (alles behalten) oder rollback (alles verwerfen).
  • Zwei Zustände pro Ressource, mehr nicht: workspace-owned (dauerhaft) oder lease-owned (temporär). workspace-owned-Zeilen können nie erneut in ein lease eintreten — der einzige Eintrittspfad ist --lease <id> zum Erstellungszeitpunkt.
  • Die TTL ist das Sicherheitsnetz. Wenn der schließende Aufruf nie geschieht, führt die Plattform beim Ablauf automatisch ein Rollback des lease aus, sodass abgebrochene Läufe keine Rechenleistung verlieren.
  • Leases sind die agent sandbox: ein LLM (oder ein Mensch) experimentiert frei innerhalb eines lease — Graph-Formen, Parameter-Tausch, Deploy und Abbau — während der workspace-owned-Zustand unberührt bleibt und das Aufräumen automatisch geschieht.
  • Leases dienen zugleich als vorhersagbare Batch-Oberfläche: fahre ein backend hoch, das einen Datensatz verarbeitet, erfasse die erzeugten Artefakte, Promote die behaltenswerten und rollback den Rest. Die fixierten Eingaben, das fixierte runtime und die adressierbaren Ausgaben machen den Batch reproduzierbar.
  • Die meisten Nutzer fassen die Verben nie direkt an. ppl lease run --test=<manifest> orchestriert den vollen Lebenszyklus für den häufigen Fall (live test aus einem Manifest).

Was ein lease tatsächlich ist

Ein lease umfasst die Ressourcen, die ein kurzlebiger Lauf erstellt — eine Kandidaten-prerelease, eine hochgeladene Fixture, ein backend, das sie umschließt, ein deployment auf einem runtime — sodass all das gemeinsam verworfen werden kann, wenn der Lauf endet, ohne verlorene Rechenleistung, Speicher oder verwaiste Graph-Zeilen.

Die Alternative ist, jede erstellte Ressource zu verfolgen und sie am Ende einzeln zu löschen, wobei das Aufräumen zuletzt läuft. Ein Absturz mitten im Lauf, ein CI-Runner, der herunterfährt, oder ein agent, der seinen Lauf beendet, bevor dieser Schritt ausgeführt wird, hinterlässt das Aufräumen halb erledigt, und die übrig gebliebene Ressource ist diejenige, die weiter Rechenleistung verbraucht.

Das lease macht die Aufräumgrenze zu einem erstklassigen Objekt. Das lease ist ein Geltungsbereich: öffne es, hänge Ressourcen in dem Moment an, in dem sie entstehen, indem du --lease <id> an ihren create-Aufruf stempelst, schließe es mit einer einzigen Entscheidung. Commit macht alles im lease dauerhaft und workspace-owned. Rollback entfernt alles im lease als eine einzige Operation. Wenn das Schließen nie geschieht, schließt die TTL es für dich, mit rollback als Default, weil das Aufbewahren unbekannten Zustands die gefährliche Option ist.

Ein lease hat dieselbe Form wie eine Datenbanktransaktion: ein ABORT-on-expiry, das einem connection-drop-ABORT in einer SQL-Datenbank entspricht, eine commit-oder-rollback-Wahl, die COMMIT/ROLLBACK in SQL entspricht, ein Promote pro Zeile, das savepoint-artigen partiellen Commits entspricht, und kein implizites Anhängen, weil der einzige Eintrittspfad --lease <id> zum Erstellungszeitpunkt ist. Die Transaktionssemantik überträgt sich direkt auf Cloud-Ressourcen.

Mentales Modell

   ppl lease create   ── BEGIN
       │
       │  ppl lease run / ppl file link --lease <lid>
       │       ── INSERT, lease-owned
       │       (version, fixture uploads, ephemeral
       │        backend + deployment, all stamped with
       │        the lease id at the moment they exist)
       │
       ├── ppl lease commit   <lid>   ── COMMIT
       │       → every owned row becomes workspace-owned,
       │         lease closes
       │
       ├── ppl lease rollback <lid>   ── ROLLBACK
       │       → every owned row deleted, lease closes
       │
       └── TTL elapses without close  ── ABORT-on-disconnect
               → auto-rollback, lease closes

Der Vertrag ist kurz: eine Zeile wird in dem Moment mit der lease-id gestempelt, in dem sie erstellt wird, und das ist der einzige Weg, wie eine Zeile in ein lease eintritt. Es gibt keine "hänge diese bestehende Zeile später an ein lease an"-Operation, und dieses Fehlen ist beabsichtigt. Eine Zeile ist entweder von dem Moment an im lease, in dem sie existiert, oder sie ist für immer workspace-owned. Es gibt keinen dritten Zustand, keine Race Condition und keine halb gestempelte Zeile, über die man nachdenken müsste.

Siehe Der lease-Lebenszyklus für die operative Anleitung und Deployments für das deployment, das ein lease typischerweise hält.

Zwei Muster, die leases freischalten

Verwende diesen Rahmen, um zu verstehen, warum leases als erstklassiges Primitive existieren statt als CLI-Aufräumskript.

Das erste Muster ist vorhersagbare Batch-Berechnung mit erfassten Ausgaben. Eine häufige Form ist: führe einen Datensatz durch einen backend-Graphen, lass ihn abgeleitete Artefakte schreiben (einen Vektor-Index, eine Feature-Tabelle, eine Menge zugeschnittener Bilder, ein Modell-Checkpoint), behalte die Artefakte, verwirf alles andere. Ohne leases leckt dieser Ablauf — das Test-backend, das Test-deployment und die temporären Fixtures bleiben alle zurück, und sie später zu finden bedeutet, von Hand durch den workspace-Zustand zu suchen. Mit leases ist der ganze Apparat ein gestempelter Geltungsbereich: deploye innerhalb des lease, führe den Batch aus, erfasse die Ausgaben nach Namen, Promote die behaltenen Dateien aus dem lease heraus, rollback den Rest. Die Eingaben waren fixiert, das runtime war fixiert, und die Ausgaben sind adressierbar, sodass der Batch reproduzierbar ist, weil das lease die Grenze eindeutig gemacht hat.

Das zweite Muster ist die agent sandbox. Auf der CLI-agent-Oberfläche sind destruktive Operationen entfernt — es gibt kein delete-everything-Verb im agent-Modus —, was den agent mit einem konkreten Bedürfnis zurücklässt: an einem Graph-Entwurf iterieren, Parameterkombinationen ausprobieren, einen Kandidaten deployen, ihn verwerfen und von vorne beginnen, ohne verwaiste backends und deployments zu hinterlassen. Das lease deckt dieses Bedürfnis. Der agent öffnet ein lease, arbeitet darin und führt ein Rollback aus, wenn er fertig ist. Wenn der agent seinen Lauf beendet, bevor er das lease schließt, schließt die TTL es. Die destruktive Operation, die die agent-Oberfläche nicht freilegt, ist die, die das lease sicher bereitstellt, beschränkt auf genau die Ressourcen, die der agent während dieses Laufs erstellt hat. Der workspace-owned-Zustand bleibt außerhalb der Reichweite des lease; das lease ist die umschließende Sandbox darum herum.

Das lease-Design existiert wegen dieser zwei Muster. Die Test-Harness-Bequemlichkeit ist real, aber zweitrangig; der zugrunde liegende Vertrag besteht darin, jedem ephemeren Lauf eine Transaktionsgrenze zu geben, sodass das Aufräumen automatisch geschieht und Ausgaben erstklassig sind.

Die vier Lifecycle-Verben

Verwende dies als Katalog für "was das lease selbst tun kann".

Der lease-Lebenszyklus hat genau vier Verben, und sie bilden direkt eine Datenbanktransaktion ab.

ppl lease create öffnet das lease. Es nimmt das runtime, auf dem das spätere deployment landet, eine optionale TTL, ein optionales Label und liefert die lease-ID zurück. Nachfolgende create-Aufrufe stempeln sich mit --lease <id>, um darin zu fahren.

ppl lease promote <lid> --kind <k> --id <id> ist der savepoint-artige Commit pro Zeile. Es nimmt eine einzelne lease-owned-Ressource und macht sie sofort workspace-owned, sodass sie überlebt, was auch immer mit dem Rest des lease geschieht. Das ist die richtige Form, um ein Artefakt zu behalten, während der Rest des lease wegwerfbar bleibt.

ppl lease commit <lid> schließt das lease und behält alles: jede noch besessene Zeile wird in einer einzigen atomaren Operation workspace-owned.

ppl lease rollback <lid> schließt das lease und verwirft alles: jede noch besessene Zeile wird in einer einzigen atomaren Operation zerstört. Alles, was vorher Promotet wurde, überlebt, weil es bereits workspace-owned ist.

Die ergänzenden operativen Verben sind geringer an Zahl. wait streamt den deployment-Lebenszyklus und beendet sich mit einem aussagekräftigen Code (0 für ready, 1 für failed oder timeout). debug liefert einen strukturierten Snapshot des backend, deployment und Zustands pro Container des lease zurück — der erste Aufruf, wenn ein lease fehlschlägt. set-result zeichnet eine strukturierte Ergebnis-Payload auf, die das Schließen überlebt, für die Post-mortem-Analyse. collect-outputs baut das deployment mit file-save-Semantik ab und liefert die erfassten file_ids zurück. list und delete sind Hausverwaltung.

Siehe Der lease-Lebenszyklus für die Anleitung auf Verb-Ebene.

Zustände pro Ressource

Eine Ressource auf der Plattform hat genau zwei Besitzzustände, und das lease-Design hängt von dieser Einfachheit ab.

Workspace-owned ist der dauerhafte Zustand. Die Ressource wurde ohne --lease erstellt, wurde mit --lease erstellt und dann Promotet, oder wurde mit --lease erstellt und das lease wurde Committet. Sie gehört dem workspace für immer (bis etwas sie explizit über den Vertrag für destruktive Operationen löscht).

Lease-owned ist der temporäre Zustand. Die Ressource wurde mit --lease <id> erstellt und ist noch innerhalb dieses offenen lease. Wenn das lease schließt, wird die Ressource entweder workspace-owned (commit) oder zerstört (rollback). Die TTL begrenzt den lease-owned-Zustand, sodass er nicht unbegrenzt fortbestehen kann; verlassene leases werden automatisch zurückgerollt.

Es gibt keinen dritten Zustand. Es gibt keinen "lease-attached-but-retain"-Halbzustand. Es gibt kein adopt-Verb, das workspace-owned-Zeilen nachträglich in ein lease zieht. Der Minimalismus ist der Punkt — er macht "ist diese Ressource ephemer oder dauerhaft" zu einer Ein-Bit-Frage mit einer eindeutigen Antwort zu jedem Zeitpunkt.

TTL als Sicherheitsnetz, explizites Schließen als Default

Ein lease endet auf eine von zwei Arten. Die TTL ist das passive Schließen: die Plattform rollt automatisch jedes lease zurück, dessen TTL verstrichen ist. Das explizite commit oder rollback ist das aktive Schließen: es wendet die Behalten-oder-Verwerfen-Entscheidung sofort an, statt auf die Uhr zu warten.

Der richtige Default ist das explizite Schließen. Es macht die Entscheidung bewusst, hält die lease-Liste klein und führt eine genaue Aufzeichnung darüber, warum jede Zeile existiert. Die TTL deckt die Läufe ab, die vor dem Schließen endeten, und diese Läufe sollten die Minderheit sein, nicht die Norm.

Rollback ist der TTL-Default, statt commit, weil der gefährliche Fehler darin besteht, unbekannten Zustand zu behalten. Wenn ein Lauf ohne explizites Schließen verlassen wird, behandelt die Plattform seine Ausgabe nicht als behaltenswert; die Behalten-Entscheidung liegt beim Operator, und ihr Fehlen löst sich zu rollback auf.

Wo das hinpasst

Leases schließen die Lücke zwischen "ich habe einige Ressourcen für einen Lauf erstellt" und "alle davon werden danach zuverlässig aufgeräumt" — die Lücke, in der sich über die Lebensdauer eines Projekts verwaister Zustand ansammelt. Indem die Plattform dieser Lücke einen Namen, eine Transaktionsform und ein Sicherheitsnetz gibt, macht sie das Aufräumen zu einem Vertrag, den das runtime erzwingt, statt zu einem Schritt, an den sich jeder Lauf erinnern muss. Der Preis ist ein zusätzliches Konzept (das lease); im Gegenzug teilen sich Automatisierung, agents, Batch-Jobs und live tests alle standardmäßig dieselbe Aufräumdisziplin.

Verwandt

War diese Seite hilfreich?