@opencxh/domain 1.172.1 → 1.173.0

package/dist/entities/playbook/types.d.ts

@@ -2,10 +2,10 @@ import { ActingIdentity } from '../../platform/identity';
 import { ResourceRef } from '../../platform/resource';
 import { OwnerScope } from '../scope/types';
 /**
- * Playbooks — event-driven automation met AI-stappen. Zie docs/PLAYBOOKS.md.
+ * Playbooks — event-driven automation with AI steps. See docs/PLAYBOOKS.md.
  *
- * Twee uitvoeringsvormen, één contract: zie {@link Decider}. Alle staptypes in
- * {@link Step} worden uitgevoerd; er is geen soort meer die de executor weigert.
+ * Two execution forms, one contract: see {@link Decider}. Every step type in
+ * {@link Step} is executed; there is no kind the executor refuses.
  */
 export type Autonomy = "suggest" | "auto";
 export type PlaybookTrigger = {
@@ -17,33 +17,26 @@ export type PlaybookTrigger = {
     channelIds?: string[];
     filter?: unknown;
     /**
-     * Wacht dit aantal milliseconden en draai dan **één** run voor de berichten in dat
-     * venster, in plaats van een run per bericht.
+     * Wait this many milliseconds, then run **once** for the messages in that window
+     * instead of once per message. The run executes on the **newest** message; the ones
+     * in between are already covered by the conversation lookup step.
      *
-     * Voor een playbook dat bij elk bericht een modelcall doet is dit het verschil tussen
-     * vier calls en één bij een mailwisseling van vier berichten in tien minuten. De run
-     * draait op het **nieuwste** bericht uit het venster; wat ertussen zat is in de
-     * samenvatting van dat gesprek al meegenomen via de lookup-stap.
-     *
-     * Bewust op de trigger en niet in de geheugenlaag: coalesceren is een eigenschap van
-     * "hoe vaak wil ik hierop reageren", niet van wat je onthoudt.
+     * Deliberately on the trigger, not in the memory layer: coalescing is a property of
+     * "how often do I want to react", not of what you remember.
      */
     debounceMs?: number;
 } | {
     kind: "manual";
 }
 /**
- * Iemand wijst werk aan de agent van deze playbook toe — de wekker van een **opdracht**.
- *
- * Geen nieuw mechanisme: een toewijzing is al een activity, dus dezelfde poort levert hem af.
- * Wat deze soort toevoegt is de vraag die de engine niet zelf kan beantwoorden — *is dit aan
- * míjn agent?* — en het antwoord staat in `Playbook.agentId`, niet hier. Eén plek die de
- * agent benoemt, want dat veld bepaalt óók namens wie de run handelt; zou het hier nóg een
- * keer staan, dan kon een playbook op de toewijzing aan de één reageren namens de ander.
- *
- * Wélke soorten werk toegewezen kunnen worden is **gedeclareerd** door de app die ze bezit
- * (`assignment-source`-federatie, zie `./assignment.ts`) en staat daarom als losse id in
- * `targetKind` in plaats van als union hier.
+ * Someone assigns work to this playbook's agent — the wake-up call of an **assignment**.
+ *
+ * Not a new mechanism: an assignment is already an activity, so the same gate delivers it.
+ * The question the engine cannot answer itself — *is this for MY agent?* — is answered by
+ * `Playbook.agentId`, not here: one place names the agent, because that field also decides
+ * who the run acts as. Which kinds of work can be assigned is **declared** by the app that
+ * owns them (`assignment-source` federation, see `./assignment.ts`), hence a loose id in
+ * `targetKind` instead of a union here.
  */
  | {
     kind: "assignment";
@@ -54,18 +47,16 @@ export interface Guardrails {
     maxToolCalls?: number;
 }
 /**
- * Grenzen voor `maxTokens` op een AI-stap. De bovengrens is dezelfde als die van
- * `/generate`: geen enkele prompt hier heeft meer output nodig, en een op hol
- * geslagen run mag er niet voor betalen. De ondergrens houdt een typfout ("5")
- * tegen die elk antwoord halverwege een woord afkapt.
+ * Bounds for `maxTokens` on an AI step. The upper bound matches `/generate` — no prompt here
+ * needs more output, and a runaway run must not pay for it. The lower bound blocks a typo
+ * ("5") that would truncate every answer mid-word.
  */
 export declare const STEP_MAX_TOKENS_MIN = 64;
 export declare const STEP_MAX_TOKENS_MAX = 8000;
 /**
- * `maxTokens` van een stap naar een bruikbare waarde, of `undefined` als er niets
- * (bruikbaars) staat. Neemt ook strings aan, want de editor levert het veld als
- * tekst op (`<input type="number">`) en een string in `max_tokens` is bij OpenAI
- * en Anthropic een 400.
+ * Clamp a step's `maxTokens` to a usable value, or `undefined` when there is nothing usable.
+ * Also accepts strings: the editor delivers the field as text (`<input type="number">`), and
+ * a string in `max_tokens` is a 400 at OpenAI and Anthropic.
  */
 export declare function clampStepMaxTokens(value: unknown): number | undefined;
 export interface ConditionStep {
@@ -76,12 +67,10 @@ export interface ConditionStep {
     onFalse: "stop" | "escalate" | "continue";
 }
 /**
- * Generiek over wat er in de body mag staan, zodat een beperkte staptaal een **echt subtype** kan
- * zijn in plaats van een runtime-regel. Zie `ReadStep` in `../live-lens/types`: die laat hier
- * alleen leesbare stappen in, en dan is "een leesbaan kan niet schrijven" een typefout in plaats
- * van een controle die iemand kan vergeten aan te roepen.
- *
- * De default houdt elk bestaand gebruik (`ForEachStep` zonder parameter) ongewijzigd.
+ * Generic over the step body so a restricted step language can be a **real subtype** instead
+ * of a runtime rule — see `ReadStep` in `../live-lens/types`, which only admits readable
+ * steps, making "a read lane cannot write" a type error rather than a check someone can
+ * forget. The default keeps existing usage (`ForEachStep` without a parameter) unchanged.
  */
 export interface ForEachStep<S = Step> {
     type: "for-each";
@@ -103,45 +92,36 @@ export interface ActionStep {
     params: Record<string, unknown>;
     autonomy?: Autonomy;
     /**
-     * Var waarin het resultaat van de actie landt, als je het nodig hebt.
-     *
-     * Bestond niet, en daardoor was er geen manier om te wachten op iets dat je zelf net had
-     * aangemaakt: een `create_task` kon haar id nergens laten, dus `waitingOn: { on: "task" }` was
-     * niet in te gaan. Dezelfde vorm als `LookupStep.as`, en dezelfde parsing — twee antwoorden op
-     * "wat ís het resultaat van een tool" zou de volgende duplicatie zijn.
+     * Var that receives the action's result, when you need it (e.g. wait on a task you just
+     * created). Same shape and parsing as `LookupStep.as`.
      *
-     * Onder autonomie `suggest` wordt de actie vastgehouden en draait ze pas na goedkeuring; het
-     * resultaat landt dan bij het hervatten. Tot dat moment bestaat de var niet, en een stap die
-     * er dan al naar verwijst faalt luid (zie `engine/utils.ts`) in plaats van met leegte verder
-     * te gaan.
+     * Under autonomy `suggest` the action is held and runs only after approval; the result
+     * lands on resume. Until then the var does not exist, and a step that references it fails
+     * loudly (see `engine/utils.ts`) instead of continuing with emptiness.
      */
     as?: string;
 }
 /**
- * Wacht tot deze taak af is.
- *
- * De tegenhanger van `wait-for-reply`, voor het geval uit de support-procedure: "moet een
- * collega iets doen, maak een taak en wacht tot die af is". `taskId` is een gewone verwijzing,
- * dus `$newTask.id` na een `create_task` met een `as`.
+ * Wait until this task is done. Counterpart of `wait-for-reply`, for the support-procedure
+ * case "a colleague must do something: create a task and wait for it". `taskId` is an
+ * ordinary reference, e.g. `$newTask.id` after a `create_task` with an `as`.
  */
 export interface WaitForTaskStep {
     type: "wait-for-task";
-    /** `$ref` of letterlijk id van de taak om op te wachten. */
+    /** `$ref` or literal id of the task to wait on. */
     taskId: string;
 }
 /**
- * Een enkele classificatie met gestructureerde uitvoer.
+ * A single classification with structured output.
  *
- * **`profileId` en niet `accountId` + `model`.** Dit was de enige AI-stap die zijn eigen account
- * en model droeg, terwijl de kernkeuze van dit systeem is dat een `AIProfile` het herbruikbare
- * brein is en AI-stappen daarnaar verwijzen (`docs/PLAYBOOKS.md` §2). Wat die uitzondering kostte:
- * sjablonen hadden `$default`/`$defaultModel`-placeholders nodig die de installer moest
- * vervangen, en een modelwissel raakte elke classify-stap van elke playbook afzonderlijk.
+ * **`profileId`, not `accountId` + `model`.** An `AIProfile` is the reusable brain and AI
+ * steps reference it (`docs/PLAYBOOKS.md` §2); carrying account/model here forced
+ * `$default`-placeholders on templates and made a model swap touch every classify step.
  */
 export interface ClassifyStep {
     type: "classify";
     as: string;
-    /** Het brein dat classificeert. Een goedkoop, snel profiel is hier de bedoeling. */
+    /** The brain that classifies. A cheap, fast profile is the intent here. */
     profileId: string;
     mode: "topics" | "question" | "extract";
     topicIds?: string[];
@@ -149,22 +129,17 @@ export interface ClassifyStep {
     fields?: unknown;
     instruction?: string;
     /**
-     * Wélke tekst geclassificeerd wordt, als `$ref` in de run-vars. Default `$trigger.text`.
-     *
-     * Nodig zodra de trigger zelf geen tekst draagt. Een `INTERACTION_STATUS_CHANGED`-activity
-     * heeft alleen `{ fromStatus, toStatus }` in zijn payload, dus `trigger.text` is leeg — en
-     * dan krijgt het model een lege invoer. Met `input: "$thread"` leest de stap wat een
-     * eerdere `lookup` heeft opgehaald, zoals de berichten van het gesprek.
+     * Which text is classified, as a `$ref` into the run vars. Default `$trigger.text`.
+     * Needed when the trigger carries no text: an `INTERACTION_STATUS_CHANGED` activity has
+     * only `{ fromStatus, toStatus }`, so `trigger.text` is empty. With `input: "$thread"` the
+     * step reads what an earlier `lookup` fetched.
      */
     input?: string;
     /**
-     * Plafond op de output van deze stap, per model-call. Leeg = het
-     * `providerConfig` van het account/profiel, en anders de vendor-default.
-     *
-     * Bewust naast `guardrails` en niet erin: `maxSteps`/`maxToolCalls` begrenzen de
-     * hele run, dit geldt per call. In dezelfde bak zou het lezen als "totaalbudget
-     * voor deze stap", en dat is het niet — een agent-loop van vijf turns mag vijf
-     * keer tot dit plafond komen.
+     * Output cap for this step, per model call. Empty = the account/profile `providerConfig`,
+     * else the vendor default. Deliberately next to `guardrails`, not inside:
+     * `maxSteps`/`maxToolCalls` bound the whole run, this applies per call — an agent loop of
+     * five turns may reach this cap five times.
      */
     maxTokens?: number;
 }
@@ -174,26 +149,22 @@ export interface GenerateStep {
     goal?: string;
     kind: "reply" | "compose" | "note";
     as?: string;
-    /** Plafond op de output van deze stap. Zie `ClassifyStep.maxTokens`. */
+    /** Output cap for this step. See `ClassifyStep.maxTokens`. */
     maxTokens?: number;
 }
 /**
- * Een agentische beurt **binnen een flow**.
- *
- * Draagt een {@link Procedure} in plaats van diens velden nóg een keer: dit had
- * `goal`/`toolsOverride`/`guardrails`/`maxTokens` als eigen velden, wat exact dezelfde vijf
- * dingen waren onder twee namen — en `runAgentStep` was een adapter die `goal` op `text` en
- * `toolsOverride` op `tools` afbeeldde. Compositie in plaats van een tweede naamgeving.
+ * An agentic turn **inside a flow**. Carries a {@link Procedure} instead of repeating its
+ * fields — composition instead of a second naming of the same five things.
  *
- * `profileId` staat hiér en niet in de procedure: een workflow heeft geen agent, dus het brein
- * moet uit de stap komen. Bij een **opdracht** komt het brein van de agent
- * (`User.profileId`) en draagt de procedure er dus geen.
+ * `profileId` lives here, not in the procedure: a workflow has no agent, so the brain must
+ * come from the step. On an **assignment** the brain comes from the agent (`User.profileId`)
+ * and the procedure carries none.
  */
 export interface AgentStep {
     type: "agent";
-    /** Het brein voor deze stap. */
+    /** The brain for this step. */
     profileId: string;
-    /** Wat er moet gebeuren, en waarbinnen. */
+    /** What must happen, and within which bounds. */
     procedure: Procedure;
     autonomy?: Autonomy;
     as?: string;
@@ -203,85 +174,65 @@ export interface WaitForReplyStep {
     deadline?: number;
 }
 /**
- * Meerdere takken tegelijk, en pas verder als ze allemaal klaar zijn.
+ * Multiple branches at once; continue only when all are done. Exists because sequential
+ * lookups cost the sum and live-assist cadence can only afford the slowest.
  *
- * Bestaat voor één concreet probleem: stappen liepen strikt sequentieel, en drie lookups van
- * elk ~1200 ms achter elkaar passen niet in een cadans van seconden (live assist). Sequentieel
- * kost de som, parallel kost de langzaamste.
+ * **Read-only.** A branch may not pause — no approval, no waiting for a reply. Not a
+ * temporary limitation: a run pausing mid fan-out would need a second state machine next to
+ * `waitingOn`. Writes go in a step after the `parallel`.
  *
- * **Alleen lezen.** Een tak mag niet pauzeren — geen goedkeuring, geen wachten op een antwoord.
- * Dat is geen tijdelijke beperking maar een grens die het begrip eenvoudig houdt: een run die
- * halverwege een fan-out pauzeert zou moeten onthouden welke takken al klaar waren en waar hij
- * verder moet, en dat is een tweede toestandsmachine naast `waitingOn`. Wie iets wil schrijven
- * doet dat in een stap ná de `parallel`.
- *
- * Elke tak schrijft naar zijn eigen `as`-namen; twee takken die dezelfde naam vullen is een
- * fout, want wie er wint hangt dan van de timing af.
+ * Each branch writes to its own `as` names; two branches filling the same name is an error,
+ * because the winner would depend on timing.
  */
 export interface ParallelStep<S = Step> {
     type: "parallel";
-    /** Elke tak is een eigen rijtje stappen. Zie {@link ForEachStep} over de parameter. */
+    /** Each branch is its own list of steps. See {@link ForEachStep} about the parameter. */
     branches: S[][];
     /**
-     * Hoeveel takken er tegelijk mogen lopen. Leeg = alle.
-     *
-     * Een plafond bestaat omdat een tak een tool-call is: tien takken tegelijk zijn tien
-     * gelijktijdige aanroepen naar andere apps.
+     * How many branches may run at once. Empty = all. A cap exists because a branch is a tool
+     * call: ten branches are ten concurrent calls into other apps.
      */
     maxConcurrent?: number;
     /**
-     * Wat een falende tak betekent. Default `"fail"`: de stap faalt.
-     *
-     * `"continue"` laat de andere takken staan en gaat door — dat is wat een leesoppervlak wil
-     * (één kapotte baan mag de andere twee niet wissen), en precies waarom het een keuze is en
-     * geen aanname.
+     * What a failing branch means. Default `"fail"`: the step fails. `"continue"` keeps the
+     * other branches and proceeds — what a read surface wants (one broken lane must not wipe
+     * the other two), which is exactly why it is a choice and not an assumption.
      */
     onBranchError?: "fail" | "continue";
 }
 export type Step = ConditionStep | ForEachStep | ParallelStep | LookupStep | ActionStep | ClassifyStep | GenerateStep | AgentStep | WaitForReplyStep | WaitForTaskStep;
 /**
- * Een **procedure**: hoe een scenario aangepakt wordt, als prose met guardrails.
- *
- * Dit is de tweede uitvoeringsvorm naast `Step[]`, en {@link AgentStep} is er de
- * variant-binnen-een-flow van (die *bevat* er een, en herhaalt zijn velden niet).
- *
- * **Geen `profileId`.** Dat stond hier, en het was de tweede brein-verwijzing in het systeem:
- * `User.profileId` bestaat al — verplicht bij het aanmaken van een agent, met als doc "het brein
- * van een agent" — en de engine las hem nooit. Twee velden voor één feit, zonder dat iets ze aan
- * elkaar relateerde: `agentId: Alice` met het brein van Bob werd zonder klacht opgeslagen, en de
- * tijdlijn zei dan Alice terwijl het model, de tools en de prompt van Bob waren.
+ * A **procedure**: how a scenario is handled, as prose with guardrails. The second execution
+ * form next to `Step[]`; {@link AgentStep} is its inside-a-flow variant (it *contains* one).
  *
- * Nu is er één antwoord op "met welk brein": bij een opdracht dat van de agent, bij een
- * agent-stap in een workflow dat van de stap. De procedure beschrijft het scenario, niet wie het
- * uitvoert.
+ * **No `profileId`.** One answer to "which brain": on an assignment the agent's
+ * (`User.profileId`), on an agent step the step's. The procedure describes the scenario, not
+ * who executes it.
  *
- * `tools` is **narrowing-only**: het moet een deelverzameling zijn van `enabledTools` van het
- * brein dat hem uitvoert. Het profiel is de identiteit (één per agent), de procedure het scenario
- * (veel per agent), en een scenario mag nooit méér mogen dan de identiteit die het uitvoert.
+ * `tools` is **narrowing-only**: it must be a subset of the executing brain's
+ * `enabledTools`. The profile is the identity (one per agent), the procedure the scenario
+ * (many per agent), and a scenario may never be allowed more than the identity executing it.
  */
 export interface Procedure {
-    /** De prose zelf — wat er moet gebeuren, in de woorden van wie het opschreef. */
+    /** The prose itself — what must happen, in the words of whoever wrote it down. */
     text: string;
-    /** Toegestane tools. Narrowing-only t.o.v. `enabledTools` van het brein. */
+    /** Allowed tools. Narrowing-only w.r.t. the brain's `enabledTools`. */
     tools?: string[];
     guardrails?: Guardrails;
-    /** Plafond per beurt. Zie `ClassifyStep.maxTokens`. */
+    /** Cap per turn. See `ClassifyStep.maxTokens`. */
     maxTokens?: number;
 }
 /**
- * Wie kiest de volgende zet.
+ * Who picks the next move. Two execution forms, one contract — both run through the same
+ * tool runtime and the same approval gate:
  *
- * Twee uitvoeringsvormen, één contract. Beide lopen door dezelfde toolruntime en dezelfde
- * goedkeuringspoort; alleen de manier waarop de volgende zet gekozen wordt verschilt:
+ * - **workflow** — deterministic `Step[]`, built on the canvas. Routing, triage, background
+ *   automation. A free, testable gate instead of a prompt.
+ * - **procedure** — prose, a model chooses. For work whose steps are not branches in a tree.
  *
- * - **workflow** — deterministisch, `Step[]`, gebouwd op de canvas. Routing, triage,
- *   achtergrondautomatisering. Een gratis, testbare poort in plaats van een prompt.
- * - **procedure** — prose, een model kiest. Voor werk waarvan de stappen geen takken in een
- *   boom zijn (antwoorden *én* een taak maken, of eerst vragen en daarna alsnog antwoorden).
- *
- * Verkeerd om gebruikt faalt elke vorm op zijn eigen manier: een procedure als workflow
- * verspreidt logica over blokken tot het onbeheersbaar is, een workflow als procedure ruilt een
- * testbare conditie voor een onbetrouwbare prompt (en kost een modelaanroep per bericht).
+ * Misused, each form fails its own way: a procedure-as-workflow scatters logic across blocks
+ * until unmanageable; a workflow-as-procedure trades a testable condition for an unreliable
+ * prompt (and costs a model call per message).
  */
 export type Decider = {
     kind: "workflow";
@@ -291,32 +242,15 @@ export type Decider = {
     procedure: Procedure;
 };
 /**
- * **Eén veld, met de soort erin.** Dit was een paar losse kolommen — `steps: Step[]` naast
- * `procedure?: Procedure | null` — met een functie (`deciderOf`) die er een union van maakte
- * volgens de regel "procedure aanwezig ⇒ procedure".
- *
- * Wat die vorm kostte:
- *
- * - een rij met **beide** gevuld was representeerbaar, en betekende stil "de steps zijn dood";
- * - elk schrijfpad moest de onuitgesproken regel kennen: `crud/update.ts` moest expliciet `null`
- *   schrijven om "de procedure eruit halen" te laten werken, en `run-playbook.ts` had een
- *   conditionele spread om de kolom weg te laten;
- * - de frontend had de regel nóg een keer (`!!pb.procedure` als soort-filter);
- * - en het is al een keer stil fout gegaan: `fromView` droeg `procedure` niet mee, waardoor élke
- *   procedure die je opende en opsloeg zichzelf tot een lege workflow maakte.
- *
- * Met `kind` in de kolom is de soort een feit in plaats van een gevolgtrekking, en kan er geen
- * derde toestand bestaan. De editor houdt zijn platte vorm — dat is wat `toView`/`fromView` doen.
+ * One field with the kind inside: a row cannot carry both steps and a procedure, so the sort
+ * is a fact rather than an inference from which columns happen to be filled (which once made
+ * every opened-and-saved procedure silently become an empty workflow). The editor keeps its
+ * flat form — that is what `toView`/`fromView` do.
  */
 export declare const EMPTY_WORKFLOW: Decider;
-/**
- * De stappen van deze decider, of een lege lijst als het een procedure is.
- *
- * Twee lezers-helpers en géén `deciderOf` terug: het verschil is dat deze de soort *lezen* in
- * plaats van hem te *raden* uit welke velden gevuld zijn.
- */
+/** The steps of this decider, or an empty list when it is a procedure. */
 export declare function stepsOf(decider: Decider | undefined): Step[];
-/** De procedure van deze decider, of `undefined` als het een workflow is. */
+/** The procedure of this decider, or `undefined` when it is a workflow. */
 export declare function procedureOf(decider: Decider | undefined): Procedure | undefined;
 export interface Playbook {
     id: string;
@@ -327,18 +261,16 @@ export interface Playbook {
     enabled: boolean;
     autonomy: Autonomy;
     trigger: PlaybookTrigger;
-    /** Wie de volgende zet kiest: stappen of prose. Zie {@link Decider}. */
+    /** Who picks the next move: steps or prose. See {@link Decider}. */
     decider: Decider;
     /**
-     * De agent die dit uitvoert: het `userId` van een gebruiker met `type: "agent"`.
+     * The agent that executes this: the `userId` of a user with `type: "agent"`. Determines
+     * **who the run acts as** (`runActor`): whose name is on the timeline, which interactions
+     * it may touch, whose budget it draws from.
      *
-     * Bepaalt **namens wie** de run handelt (`runActor`), en daarmee: wiens naam er in de tijdlijn
-     * staat, welke interacties hij mag raken, en van wiens budget het afgaat. Bewust náást
-     * `ownerScope` en niet erin — dat veld bepaalt wie de playbook mag *beheren*, en dat blijven
-     * mensen. Een agent logt nooit in, dus als beide op één veld leunden kon niemand hem meer
-     * aanpassen.
-     *
-     * Leeg = de actor volgt de scope, precies zoals voorheen.
+     * Deliberately next to `ownerScope`, not inside it — that field says who may *manage* the
+     * playbook, and those stay humans; an agent never logs in, so if both leaned on one field
+     * nobody could edit it anymore. Empty = the actor follows the scope.
      */
     agentId?: string | null;
     /** Bumped on every change; runs pin to the version they started on. */
@@ -353,106 +285,77 @@ export interface Playbook {
     };
 }
 /**
- * Levenscyclus van een run. Geen `pending`: runs worden ingevoegd als `running` en
- * de `PLAYBOOK_STARTED`-activity dekt "hij is begonnen" al. (Die status bestond,
- * werd nooit geproduceerd, en had wél een label in de UI.)
+ * Run lifecycle. No `pending`: runs are inserted as `running`, and the `PLAYBOOK_STARTED`
+ * activity already covers "it has begun".
  */
 export type RunStatus = "running" | "waiting" | "done" | "escalated" | "failed" | "stopped";
 /**
- * Waaróp een wachtende run wacht.
- *
- * Dit was eerder statusinformatie: `awaiting_approval`, `awaiting_reply` en `timed_out` waren
- * drie statussen die alle drie "wacht op X" betekenden, en de reden zat in de naam. Daardoor
- * groeide de statusset met elke nieuwe reden mee — een run die op een taak wacht zou
- * `awaiting_task` hebben gevraagd, een run die op een moment wacht `awaiting_time`, en dan
- * moest elke lezer van `status` opnieuw worden bijgewerkt.
- *
- * De reden van het wachten is **data**, geen status. `status: "waiting"` zegt dát er gewacht
- * wordt; dit veld zegt waarop, en wie het signaal levert leest alleen dit.
+ * What a waiting run is waiting for. The reason is **data**, not status: `status: "waiting"`
+ * says that it waits, this field says what for — a new reason costs a member here, not a new
+ * status every reader must learn.
  *
- * `timed_out` staat er niet bij: een verstreken deadline is geen manier van wachten maar een
- * uitkomst, en landt via `decideFinalState` op een eindstand (zie {@link TerminalLifecycle}).
- *
- * Er is ook geen `{ on: "time" }`. Die stond hier, zonder dat iets hem schreef of las: het
- * wachten-op-een-moment dat wél bestaat is de timeout-job die bij `{ on: "reply" }` wordt
- * ingeplanned, en die leest de deadline uit de job en niet uit dit veld. Een lid dat door niets
- * geproduceerd wordt is een belofte aan elke lezer die hem moet afhandelen.
+ * No `timed_out`: an expired deadline is an outcome, not a way of waiting, and lands on a
+ * terminal state via `decideFinalState` (see {@link TerminalLifecycle}). No `{ on: "time" }`
+ * either: nothing produced or read it; the reply-timeout job carries its own deadline.
  */
 export type WaitingOn = {
     on: "approval";
 }
-/** De klant antwoordt, of een collega beantwoordt de interne vraag van de run. */
+/** The customer replies, or a colleague answers the run's internal question. */
+/** `interactionId` only when the subject is a conversation; a work item waits without one. */
  | {
     on: "reply";
-    interactionId: string;
+    interactionId?: string;
 } | {
     on: "task";
     taskId: string;
 };
-/** Eindstanden: hier komt een run niet meer vanzelf uit. */
+/** Terminal states: a run does not leave these on its own. */
 export declare const TERMINAL_RUN_STATUSES: readonly ["done", "escalated", "failed", "stopped"];
 /**
- * **Tweede vocabulaire, expliciet.** Waarom een run eindigde, zoals de tijdlijn het benoemt —
- * niet hetzelfde als de status die op de run staat.
- *
- * Twee redenen zijn geen `RunStatus`, en dat is geen omissie:
+ * **A second vocabulary, on purpose.** Why a run ended, as the timeline names it — not the
+ * same as the status on the run:
  *
- * - **`rejected`** — een afgewezen voorstel landt als status `"stopped"`, maar de tijdlijn moet
- *   "afgewezen" kunnen zeggen.
- * - **`timed_out`** — een run waarvan de deadline verstreek landt als `"escalated"` (er moet een
- *   mens iets mee), maar "geen antwoord binnen de deadline" is een andere mededeling dan
- *   "geëscaleerd". Dit was eerder een eigen status; hij is verhuisd naar dit vocabulaire, want
- *   het is een *reden* en geen toestand waar een run in kan verkeren.
+ * - **`rejected`** — a rejected proposal lands as status `"stopped"`, but the timeline must
+ *   be able to say "rejected".
+ * - **`timed_out`** — a missed deadline lands as `"escalated"` (a human must act), but "no
+ *   reply within the deadline" is a different message. A *reason*, not a state.
  *
- * Dat dit vocabulaire rijker is dan de statusset is precies waarom het apart bestaat: de
- * tijdlijn vertelt een mens wát er gebeurde, `status` vertelt de machine wat er nog te doen is.
+ * The timeline tells a human what happened; `status` tells the machine what is left to do.
  */
 export type TerminalLifecycle = RunStatus | "rejected" | "timed_out";
 /**
- * Is deze run klaar — en daarmee ook: mag hij opnieuw gedraaid worden?
- *
- * Die tweede vraag had een eigen functie (`isRetryable`) die niets anders deed dan deze
- * aanroepen. Twee namen voor één regel betekent dat een lezer moet uitzoeken of er een verschil
- * is; dat er geen was, was niet te zien zonder de body te openen.
- *
- * De regel zelf staat hier dus één keer: een retry mag op precies de eindstanden. Een lopende of
- * mens-gepauzeerde run blijft met rust, zodat een retry nooit over live uitvoering heen loopt of
- * een openstaand voorstel overschrijft.
+ * Is this run finished — and thereby: may it be retried? A retry is allowed on exactly the
+ * terminal states; a running or human-paused run stays untouched, so a retry never runs over
+ * live execution or overwrites an open proposal.
  */
 export declare function isTerminal(status: RunStatus | string): boolean;
 /**
- * Wacht deze run op iets externs?
- *
- * Eén statusvergelijking en niet meer een lijst: er was een `PAUSED_RUN_STATUSES` met twee
- * leden omdat de reden van het wachten ín de status zat. Nu staat de reden in
- * {@link WaitingOn} en is "wacht" één toestand — dus een nieuwe reden (een taak, een moment)
- * verandert deze functie niet meer.
+ * Is this run waiting on something external? One status comparison: the reason lives in
+ * {@link WaitingOn}, so a new wait reason does not change this function.
  */
 export declare function isPaused(status: RunStatus | string): boolean;
 /**
- * Loopt deze run nog — mag `finalizeRun` er een uitkomst over schrijven?
- *
- * "In de lucht" is precies "niet in een eindstand": `running` of `waiting`. De lock-retry in
- * `jobs/context.ts` herschedulet tot vijf keer, dus zonder deze check kan een late job met een
- * verouderde uitkomst over een al afgeronde run schrijven.
+ * Is this run still live — may `finalizeRun` write an outcome for it? "Live" is exactly "not
+ * terminal": `running` or `waiting`. The lock retry in `jobs/context.ts` reschedules up to
+ * five times, so without this check a late job could write a stale outcome over a finished
+ * run.
  */
 export declare function isInFlight(status: RunStatus | string): boolean;
 /**
- * Het onderwerp van een run als één verwijzing, of `undefined` als hij er geen heeft.
- *
- * Zo'n run bestaat: een org-brede playbook die een rollup doet heeft geen resource om over te
- * gaan. Dat is een geldige toestand en geen ontbrekend veld.
+ * The run's subject as one reference, or `undefined` when it has none. Such runs exist: an
+ * org-wide rollup playbook has no resource to be about — a valid state, not a missing field.
  */
 export declare function subjectOf(run: {
     subjectKind?: string;
     subjectId?: string;
 }): ResourceRef | undefined;
-/** De scope-sleutel van het onderwerp, klaar voor `authorizeScope`. */
+/** The subject's scope key, ready for `authorizeScope`. */
 export declare function subjectKeyOf(run: {
     subjectKind?: string;
     subjectId?: string;
 }): string | undefined;
-/** Het interactie-id van deze run, als zijn onderwerp een gesprek is. */
+/** This run's interaction id, when its subject is a conversation. */
 export declare function runInteractionId(run: {
     subjectKind?: string;
     subjectId?: string;
@@ -464,20 +367,14 @@ export interface RunStepTrace {
     note?: string;
     ms?: number;
 }
-/**
- * Wat deze run in beweging zette.
- *
- * Was `createdBy: string`, en dat veld droeg de auteur van de **playbook** — niet wie de run
- * startte. Dus "wie heeft dit gedaan" had geen antwoord, terwijl `run/start.ts` het userId van de
- * mens die op start drukte al meestuurde in de job-data, waar niemand het las.
- */
+/** What set this run in motion — who started the run, not the playbook's author. */
 export type StartedBy = 
-/** Een mens drukte op start (`POST /playbook-run/start`). */
+/** A human pressed start (`POST /playbook-run/start`). */
 {
     kind: "user";
     id: string;
 }
-/** De trigger vuurde: een activity, een toewijzing, een afgeronde taak. */
+/** The trigger fired: an activity, an assignment, a completed task. */
  | {
     kind: "trigger";
     id?: string;
@@ -488,40 +385,29 @@ export interface PlaybookRun {
     playbookId: string;
     playbookVersion: number;
     /**
-     * De opdracht waarvan dit een **beurt** is, als er een is.
-     *
-     * Afwezig = een losstaande uitvoering (een automatisering die vuurt en klaar is). Aanwezig = één
-     * zet in werk dat langer leeft dan deze run, met een draad als geheugen.
+     * The assignment this is a **turn** of, if any. Absent = a standalone execution (an
+     * automation that fires and is done). Present = one move in work that outlives this run,
+     * with a thread as memory.
      */
     assignmentId?: string;
     /**
-     * Waar deze run **over gaat**, in twee platte kolommen.
-     *
-     * Dit was `interactionId?: string`, en dat leek onschuldig — het veld was immers optioneel. Maar
-     * vier paden leunden er zwijgend op alsof het verplicht was: goedkeuren gooide `400` zonder
-     * interactie, de lijst filterde op `audience` (leeg voor een org-actor, dus onvindbaar), de
-     * tijdlijn deed niets, en de taak-wekker eiste een gesprek. Precies het geval waar de
-     * toewijs-federatie voor bestaat — werk dat géén gesprek is — viel dus in dat gat.
-     *
-     * **Twee kolommen en geen genest object**, om dezelfde reden als {@link WaitingOn} zijn
-     * `waitingOnKind` heeft: de store kan niet in een genest object zoeken, en hier moet op gezocht
-     * worden (de runs van dit gesprek, de runs van deze taak). `subjectOf` maakt er een
-     * {@link ResourceRef} van waar je hem als geheel nodig hebt.
+     * What this run is **about**, in two flat columns — not a nested object, for the same
+     * reason {@link WaitingOn} has its `waitingOnKind`: the store cannot search inside a
+     * nested object, and these must be queryable (the runs of this conversation, of this
+     * task). Genuinely optional: assignment-federation work that is not a conversation has no
+     * interaction. `subjectOf` builds a {@link ResourceRef} where you need it whole.
      */
     subjectKind?: string;
     subjectId?: string;
     status: RunStatus;
     /**
-     * De aanleiding: wélk signaal deze run startte, plus de invoer zoals die er tóen uitzag.
+     * The cause: which signal started this run, plus the input as it looked **then**.
      *
-     * **`vars` hier is niet hetzelfde als `vars.trigger` hieronder, en dat is met opzet.** Dit veld
-     * is de *onveranderlijke invoer*; `vars` is de *werkkopie* die tijdens de run muteert — stappen
-     * schrijven erin, en resume-on-reply overschrijft `vars.trigger` met het nieuwe bericht. Een
-     * retry moet schoon herrekenen vanaf het oorspronkelijke signaal, en dat kan alleen als dat
-     * signaal ergens bewaard is gebleven.
-     *
-     * Het veld heette `event`, wat suggereerde dat het de rauwe activity was; het zijn de
-     * trigger-vars. Dezelfde vorm als `vars.trigger` betekent hier dus niet dezelfde betekenis.
+     * **`vars` here is not the same as `vars.trigger` below, on purpose.** This field is the
+     * *immutable input*; `vars` is the *working copy* that mutates during the run — steps
+     * write into it, and resume-on-reply overwrites `vars.trigger` with the new message. A
+     * retry must recompute cleanly from the original signal, which requires that signal to
+     * have been kept somewhere.
      */
     trigger: {
         activityType?: string;
@@ -531,27 +417,26 @@ export interface PlaybookRun {
     vars: Record<string, unknown>;
     trace: RunStepTrace[];
     /**
-     * De uitvoeringsvorm, vastgepind bij de start: de playbook bijstellen mag een lopende of
-     * geparkeerde run niet halverwege van gedrag of opdracht laten wisselen (docs 11.4).
+     * The execution form, pinned at start: editing the playbook must not switch a running or
+     * parked run's behaviour or mandate mid-flight (docs 11.4).
      */
     decider: Decider;
     /**
-     * De agent die deze run uitvoert, vastgepind — en daarmee ook **met welk brein**: dat is
-     * `User.profileId` van deze agent. Afwezig bij een workflow zonder agent; dan draagt een
-     * agent-stap zijn eigen `profileId`.
+     * The agent executing this run, pinned — and thereby **which brain**: this agent's
+     * `User.profileId`. Absent for a workflow without an agent; an agent step then carries its
+     * own `profileId`.
      */
     agentId?: string | null;
     /**
-     * Namens wie deze run handelt, vastgepind bij de start — net als `steps`. Anders
-     * wisselt een lopende of geparkeerde run stilletjes van identiteit zodra iemand de
-     * playbook van "Alleen ik" naar "Team Finance" zet. `resume`/`retry` lezen dit veld,
-     * niet `playbook.ownerScope`.
+     * Who this run acts as, pinned at start — like `steps`. Otherwise a running or parked run
+     * silently switches identity the moment someone moves the playbook from "Only me" to
+     * "Team Finance". `resume`/`retry` read this field, not `playbook.ownerScope`.
      */
     actor?: ActingIdentity;
     /**
-     * Held action(s) awaiting human approval (autonomy: suggest) — a batch per paused
-     * step. `null` wanneer het veld gewist is; de store schrijft `null`, dus dat staat
-     * ook in het type in plaats van dat elke lezer drie toestanden moet aankunnen.
+     * Held action(s) awaiting human approval (autonomy: suggest) — a batch per paused step.
+     * `null` when the field was cleared; the store writes `null`, so the type says so instead
+     * of every reader handling three states.
      */
     pending?: {
         action: string;
@@ -561,45 +446,31 @@ export interface PlaybookRun {
     /** The AI_ACTION_PROPOSED activity created for the current pending batch (for resolve on approve/reject). */
     proposalActivityId?: string | null;
     /**
-     * Waarop deze run wacht, als `status === "waiting"`. `null` wanneer het veld gewist is (de
-     * store schrijft `null`), en afwezig bij een run die niet wacht.
-     *
-     * Vervangt de drie `awaiting_*`/`timed_out`-statussen: de reden van het wachten is data, dus
-     * een nieuwe reden kost een lid in {@link WaitingOn} en niet een status die elke lezer moet
-     * kennen.
+     * What this run waits for, when `status === "waiting"`. `null` when cleared (the store
+     * writes `null`), absent on a run that is not waiting. A new wait reason costs a member in
+     * {@link WaitingOn}, not a status every reader must know.
      */
     waitingOn?: WaitingOn | null;
     /**
-     * De **soort** van {@link WaitingOn}, als platte kolom — puur om op te kunnen queryen.
-     *
-     * `waitingOn` is een genest object en de store kan daar niet in zoeken, dus elke wekker deed
-     * `status: "waiting"` en filterde daarna in het geheugen op `run.waitingOn?.on`
-     * (`jobs/run-playbook.ts`, `triggers/from_tasks.ts`). Dat is goedkoop bij tien wachtende runs
-     * en niet bij tienduizend. Afgeleid en op één plek geschreven (`finalizeRun`), zodat hij niet
-     * uit de pas kan lopen met het object ernaast.
+     * The **kind** of {@link WaitingOn} as a flat column, purely to query on: the store cannot
+     * search inside the nested object, and filtering `status: "waiting"` in memory is cheap at
+     * ten waiting runs and not at ten thousand. Derived and written in one place
+     * (`finalizeRun`) so it cannot drift from the object next to it.
      */
     waitingOnKind?: WaitingOn["on"] | null;
     /**
-     * Index van de stap waarop de flow pauzeerde — voor elke vorm van wachten.
-     * (Was `resumeIndex` naast `pending.stepIndex`: twee velden voor
-     * hetzelfde feit, in twee takken geschreven en in twee takken gelezen.)
-     *
-     * Heette `pausedAt`, wat een tijdstip suggereerde tussen velden die dat écht zijn
-     * (`lastStepAt`, `lastRunAt`, `deadline`, `until`). Het is een stap-index.
+     * Index of the step the flow paused at — for every form of waiting. A step index, not a
+     * timestamp.
      */
     resumeAtStep?: number | null;
     rounds?: number;
     /**
-     * Wie deze run in zijn lijst ziet — een **index**, geen autorisatie.
-     *
-     * Heette `audience`, en dat woord suggereerde een rechtenlijst; hij werd ook zo gebruikt in de
-     * losse tak van `authorizeRunScope` terwijl de interactie-tak hem juist bewust negeerde (de
-     * denormalisatie verouderd zodra een gesprek van inbox wisselt). Autorisatie komt nu van het
-     * onderwerp of van de scope van de definitie; dit veld is er alleen om "mijn runs" te kunnen
-     * queryen.
+     * Who sees this run in their list — an **index**, not authorization. Authorization comes
+     * from the subject or from the definition's scope; this field only exists to query "my
+     * runs".
      */
     visibleTo?: string[];
-    /** Wie deze run in beweging zette. Zie {@link StartedBy}. */
+    /** Who set this run in motion. See {@link StartedBy}. */
     startedBy: StartedBy;
     approvedBy?: string | null;
     result?: {