@wildo-ai/platform-core-shared 1.1.10 → 1.1.11

package/dist/esm/workbench/workbench-creation-plane.custom.shared.schemas.js

@@ -1,5 +1,5 @@
 import { ApplicationInterviewDepth, MetaWorkflow_ClarificationAction, MetaWorkflow_EvaluationVerdict } from '@wildo-ai/saas-models/meta-workflows';
-import { EngineCapability, HumanDecision_FieldKind, } from '@wildo-ai/saas-models';
+import { AgentWorkShortfallKind, EngineCapability, FlowsActors_Status, HumanDecision_FieldKind, } from '@wildo-ai/saas-models';
 import { z } from 'zod';
 import { initZodDecorators, StringEditMode } from '@wildo-ai/zod-decorators';
 import { WorkbenchSpecificationArtifactConcern } from './workbench-resources.custom.shared.schemas.js';
@@ -53,6 +53,8 @@ export var WorkbenchCreationPlaneBehavior;
     /** The build lane's dispatch history, one row per attempt. */
     WorkbenchCreationPlaneBehavior["BUILD_DISPATCH_PLAN"] = "creation-plane.build-dispatch-plan";
     WorkbenchCreationPlaneBehavior["BUILD_DISPATCHES"] = "creation-plane.build-dispatches";
+    /** Everything the build knows about each task (#2530): its attempts, whose failures they were, what they cost, why it has not landed. */
+    WorkbenchCreationPlaneBehavior["BUILD_TASK_RECORDS"] = "creation-plane.build-task-records";
     /** The playbook runs suspended waiting on a person. */
     WorkbenchCreationPlaneBehavior["PLAYBOOK_RUNS"] = "creation-plane.playbook-runs";
     WorkbenchCreationPlaneBehavior["WAITING_PLAYBOOK_RUNS"] = "creation-plane.waiting-playbook-runs";
@@ -201,6 +203,75 @@ export var Workbench_BuildTaskStuckReason;
      */
     Workbench_BuildTaskStuckReason["IN_FLIGHT"] = "in_flight";
 })(Workbench_BuildTaskStuckReason || (Workbench_BuildTaskStuckReason = {}));
+/**
+ * The stuck reasons a RE-ARM releases (#2530): the task is held by its own runs, and the remedy is to fix why and put it
+ * back — `WorkbenchBuildPlanTasks_Operations.REARM` is offered for these and no other.
+ *
+ * - `completed_unlanded`: a completed run holds it through the loop guard, and a re-arm releases that run.
+ * - `attempts_exhausted`: its failed runs hold it through the attempt budget, and a re-arm releases them.
+ *
+ * Left out, each because a re-arm would be the wrong remedy: `completed_awaiting_commit` (the product exists and wants
+ * accepting, and a re-arm would build it again), `parked_awaiting_answer` (a question waits), `in_flight` (a run is
+ * live), `no_document_blueprint` (no run can produce it).
+ */
+export const WORKBENCH_REARMABLE_STUCK_REASONS = [
+    Workbench_BuildTaskStuckReason.COMPLETED_UNLANDED,
+    Workbench_BuildTaskStuckReason.ATTEMPTS_EXHAUSTED,
+];
+/**
+ * Whose failure a failed coding run was (#1581), as the run's output records it.
+ *
+ * TASK runs are counted against the task's attempt budget; HOST runs (the run could not be recorded, or the turn was
+ * taken away: a mid-turn kill, a provider's 529/429, an exhausted quota, an expired login, an operator's cancel) are
+ * forgiven up to a bound. Declared here rather than beside its producer (the companion's coding dispatch) for the reason
+ * `Workbench_BuildTaskStuckReason` gives: the workbench shows it per attempt (#2530), and a browser bundle cannot import
+ * the companion.
+ */
+export var CodingRunFailureAttribution;
+(function (CodingRunFailureAttribution) {
+    /** The task's own failure: its checks went red, or its agent ran and failed at the work. Counted. */
+    CodingRunFailureAttribution["TASK"] = "task";
+    /** The host's: it could not record the run, or the turn was taken away. Forgiven, up to a bound. */
+    CodingRunFailureAttribution["HOST"] = "host";
+})(CodingRunFailureAttribution || (CodingRunFailureAttribution = {}));
+/**
+ * WHY a build task was put back in the queue (#1535) — the one question a later reader of a re-arm asks.
+ *
+ * A re-arm keeps a task's run history and adds one fact to it, on the runs it releases: they no longer hold the task,
+ * and here is why. Declared here rather than beside its producer (the companion's build dispatch) because the workbench
+ * both offers the re-arm (`WorkbenchBuildPlanTasks_Operations.REARM`) and shows each attempt's reason (#2530), and a
+ * browser bundle cannot import the companion.
+ */
+export var BuildTaskRearmReason;
+(function (BuildTaskRearmReason) {
+    /** The landing check was wrong about this task, and has been corrected. */
+    BuildTaskRearmReason["PROBE_CORRECTED"] = "probe-corrected";
+    /** A defect outside the task made its product impossible to produce, and has been fixed. */
+    BuildTaskRearmReason["BLOCKING_DEFECT_FIXED"] = "blocking-defect-fixed";
+    /** Neither of the above: an operator judged the work should run again. The note says why. */
+    BuildTaskRearmReason["OPERATOR_JUDGEMENT"] = "operator-judgement";
+    /**
+     * Set by the BUILD WAVE, never by a person (#2210): the run completed while other runs edited the same tree, and its
+     * declared product is missing from a file one of them also changed, so the loss is theirs rather than the task's. The
+     * wave re-arms the task and re-runs it alone, a bounded number of times (`MAXIMUM_INTERFERENCE_REARMS`).
+     * The run also carries the interference the wave found (`BuildTaskInterference`, companion-side).
+     *
+     * Like every re-arm it also releases the task's FAILED runs not yet re-armed, so the attempt budget starts afresh.
+     * Deliberate: the task did complete, so its earlier failures say nothing about whether the work can be done, and the
+     * interference bound still stops a task that keeps losing its product.
+     */
+    BuildTaskRearmReason["INTERFERED_BY_CONCURRENT_RUN"] = "interfered-by-concurrent-run";
+})(BuildTaskRearmReason || (BuildTaskRearmReason = {}));
+/**
+ * The reasons a PERSON may give (`wildo build rearm`, the companion's re-arm route, the workbench's `rearm` operation).
+ * The wave's own reason is left out: it asserts a measurement (a sibling changed the product's file during the run)
+ * that only the wave makes, and an operator choosing it would record a detection that never happened.
+ */
+export const OPERATOR_BUILD_TASK_REARM_REASONS = [
+    BuildTaskRearmReason.PROBE_CORRECTED,
+    BuildTaskRearmReason.BLOCKING_DEFECT_FIXED,
+    BuildTaskRearmReason.OPERATOR_JUDGEMENT,
+];
 /**
  * How far one BUILD DISPATCH got — the whole of what `GET /build/dispatches` can honestly say.
  *
@@ -229,7 +300,10 @@ export var Workbench_BuildDispatchPhase;
 (function (Workbench_BuildDispatchPhase) {
     /** Selected and handed to its executor; nothing has resolved yet. */
     Workbench_BuildDispatchPhase["SUBMITTED"] = "submitted";
-    /** A coding run was admitted and is running. Its outcome is the durable actor-task row `codingTaskId`. */
+    /**
+     * A coding run was admitted. The phase names the HAND-OFF and stays ADMITTED however the run ends: how
+     * the run stands is `Workbench_BuildDispatch.runStatus`, read off the same execution row (#2523).
+     */
     Workbench_BuildDispatchPhase["ADMITTED"] = "admitted";
     /** A companion generation step ran to completion. */
     Workbench_BuildDispatchPhase["FINISHED"] = "finished";
@@ -315,6 +389,27 @@ export const Workbench_Playbook_Schema = z.object({
      * is for. The default instance is not listed; it is the playbook itself. Absent without a line.
      */
     openInstances: z.array(z.object({ instanceKey: z.string().min(1), purpose: z.string().min(1) })).optional().isSummaryField(),
+    /*
+     * The playbook's DECLARED edges (#2530), each a reference a process map draws. With `outputOwners` (the families it
+     * writes) they make the catalogue a graph: a family feeds the playbooks that read it, which write the families that
+     * feed the next, and a composite admits its children.
+     *
+     * The family fields address the specification-artifact row of that family (its id IS the family); a family no row
+     * holds is a dangling reference, which the edge tolerates. `inputFamilyIds` and `preconditionFamilyIds` stay apart:
+     * a playbook gated on a family waits for it without reading it, and reads families it is not gated on. So does
+     * `conditionFamilyIds` (#2670): a family whose decision decides what the playbook waits for, which it never waits for.
+     */
+    /** The families it reads, from its declared inputs. */
+    inputFamilyIds: z.array(z.string().min(1).isForeignKey()).isSummaryField(),
+    /** The families its preconditions name: an artifact that must exist, be valid, be stale or decide. */
+    preconditionFamilyIds: z.array(z.string().min(1).isForeignKey()).isSummaryField(),
+    /**
+     * The families whose DECISION decides whether one of its preconditions applies: an `artifact_expected` gate's `when`
+     * (#2494). The build decomposition expects a website plan only once the capability composition decided it is NEEDED.
+     */
+    conditionFamilyIds: z.array(z.string().min(1).isForeignKey()).isSummaryField(),
+    /** The playbooks it admits as children when it is a composite, by their row id; empty otherwise. */
+    admittedPlaybookIds: z.array(z.string().min(1).isForeignKey()).isSummaryField(),
     /** When the served board was computed — the cache's honesty field, rendered as "as of". */
     computedAt: z.date().isSummaryField(),
 });
@@ -340,6 +435,24 @@ export const Workbench_BuildPlanTask_Schema = z.object({
     /** Task refs that must land first — the only thing that decides what may run next. */
     prerequisiteTaskRefs: z.array(z.string()).isSummaryField(),
 });
+/**
+ * The BUILD PLAN view's `ref` (#2531): the plan drawn as a graph, a menubar destination beside the domain model. Its
+ * nodes are the build-plan tasks and its edges their prerequisites; a node opens the task's own page.
+ *
+ * It must not contain a dot, for the reason `WORKBENCH_DOMAIN_MODEL_VIEW_REF` records: the label lookup splits the
+ * whole `composite_views.<translationRef>.<key>` path on `.`.
+ */
+export const WORKBENCH_BUILD_PLAN_VIEW_REF = 'build-plan';
+/** The label key the view's title and description hang off: the engine's `app.<ref>` derivation, restated. */
+export const WORKBENCH_BUILD_PLAN_TRANSLATION_REF = `app.${WORKBENCH_BUILD_PLAN_VIEW_REF}`;
+/**
+ * The PLAYBOOK MAP view's `ref` (#2531): the playbook catalog drawn as what unlocks what, a menubar destination beside
+ * the build plan. Its nodes are the playbooks and the families they name; its edges what each writes, reads, waits for
+ * and, as a composite, runs (the playbook row's declared edges, #2530). No dot, for the domain model's reason.
+ */
+export const WORKBENCH_PLAYBOOK_MAP_VIEW_REF = 'playbook-map';
+/** The label key the view's title and description hang off: the engine's `app.<ref>` derivation, restated. */
+export const WORKBENCH_PLAYBOOK_MAP_TRANSLATION_REF = `app.${WORKBENCH_PLAYBOOK_MAP_VIEW_REF}`;
 /**
  * One run's write record — the evidence lane behind every dispatch.
  *
@@ -594,6 +707,13 @@ export var WorkbenchBuildPlanTasks_Operations;
      * A non-ready task answers 409 naming what it waits on. Costs a coding run.
      */
     WorkbenchBuildPlanTasks_Operations["DISPATCH_TASK"] = "dispatch_task";
+    /**
+     * Put THIS task back in the queue once the reason it did not land is fixed (#1535, #2530): its completed runs that
+     * still hold it, and its failed runs not yet re-armed, stop counting, each recording why. Offered for a task held by
+     * either guard (`completed_unlanded`, `attempts_exhausted`); a task with no such run answers 409, since there is
+     * nothing to release. Runs nothing itself: the next dispatch offers the task again.
+     */
+    WorkbenchBuildPlanTasks_Operations["REARM"] = "rearm";
     /**
      * ACCEPT what this task's latest completed coding run wrote: commit exactly those paths, from the
      * coding-run write register, in one commit whose message names the task. Paths carrying another
@@ -691,6 +811,13 @@ export const Workbench_BuildPlanDispatchTaskRequest_Schema = z.object({
     /** The conversation this dispatch belongs to, so the thread shows the run as a card. */
     conversationId: z.string().min(1).optional(),
 });
+/** Why a build task goes back in the queue (#2530): a person's reason, and what was fixed. */
+export const Workbench_BuildTaskRearmRequest_Schema = z.object({
+    /* A person's reasons only: the wave's own records a detection only the wave makes. */
+    reason: z.enum(OPERATOR_BUILD_TASK_REARM_REASONS).systemEnum('BuildTaskRearmReason'),
+    /** What was fixed, in a sentence. Required: a reason alone cannot say which defect. */
+    note: z.string().trim().min(1),
+});
 export const Workbench_AcceptChangesRequest_Schema = z.object({
     /** Commit paths that diverged since the run. NOT defaulted on — a human edit is never silently swept in. */
     force: z.boolean().optional(),
@@ -725,10 +852,27 @@ export const Workbench_PlaybookRunOutcome_Schema = z.looseObject({
     status: z.enum(Workbench_PlaybookRunOutcomeStatus).optional(),
     note: z.string().optional(),
 });
+/**
+ * How a build dispatch answers (#2531 review M1): the companion forwards its dispatch result as it is. One task run
+ * answers the task it dispatched (`plan`) and what started for it, a coding run's `admission` or the result of a
+ * `generationStep` the companion ran itself, exactly one of the two. A parallel `dispatch_next` answers the `wave` it
+ * started, with a `note`.
+ *
+ * There is no top-level `taskRef`. This schema declared one, which no answer ever carried, so the line saying what a run
+ * started was never shown and the raw answer opened in its place.
+ */
 export const Workbench_BuildPlanDispatchOutcome_Schema = z.looseObject({
-    taskRef: z.string().optional(),
+    plan: z.looseObject({ taskRef: z.string().min(1) }).optional(),
+    admission: z.looseObject({}).optional(),
+    generationStep: z.looseObject({}).optional(),
+    wave: z.looseObject({}).optional(),
     note: z.string().optional(),
 });
+/** How a re-arm answers: the runs it released, and the reason it recorded on them. */
+export const Workbench_BuildTaskRearmOutcome_Schema = z.looseObject({
+    rearmedRunTaskIds: z.array(z.string()).optional(),
+    rearm: z.looseObject({ reason: z.enum(BuildTaskRearmReason), note: z.string(), rearmedAt: z.string() }).optional(),
+});
 export const Workbench_BuildPlanAddTaskOutcome_Schema = z.looseObject({
     taskRef: z.string().optional(),
     /** TRUE when no plan existed and this task is its first. */
@@ -739,6 +883,13 @@ export const Workbench_BuildPlanAddTaskOutcome_Schema = z.looseObject({
 });
 /** How ACCEPT answers, for a task's coding run or a playbook run alike: what was committed, what was refused and why. */
 export const Workbench_AcceptChangesOutcome_Schema = z.looseObject({
+    /**
+     * TRUE when no new commit was made because what it would commit was already committed: the run was accepted before, or
+     * its files were committed by hand (#2531 review M3). `commitSha` is then that earlier commit, not a new one. An accept
+     * can be partial, holding back the files it cannot vouch for, and the task waits on them; only a forced accept
+     * (`force`) commits those.
+     */
+    alreadyCommitted: z.boolean().optional(),
     commitSha: z.string().optional(),
     committedPaths: z.array(z.string()).optional(),
     refusedPaths: z.array(z.object({ path: z.string(), reason: z.string() })).optional(),
@@ -858,7 +1009,10 @@ export const Workbench_BuildDispatchPlan_Schema = z.object({
     landedCount: z.number().int().isSummaryField(),
 });
 export const Workbench_BuildDispatch_Schema = z.object({
-    /** Emitted by the behavior as `<taskRef>--<startedAt>`, sanitized — a task can be dispatched twice. */
+    /**
+     * The dispatch's own EXECUTION id (#2530): a task can be dispatched twice, even in the same second, and was keyed on its
+     * task and start instant until two such attempts shared one id.
+     */
     workbenchBuildDispatchId: z.string().min(1).isPrimaryKey().isSummaryField(),
     /** The build-plan task this attempt ran. */
     taskRef: z.string().min(1).isSummaryField(),
@@ -890,18 +1044,318 @@ export const Workbench_BuildDispatch_Schema = z.object({
     codingTaskId: z.string().min(1).isForeignKey().isSummaryField().nullable(),
     /** Why it failed, verbatim. NULL on every dispatch that did not. */
     error: z.string().min(1).isSummaryField().nullable(),
+    /**
+     * Whose failure a failed coding run was (#1581): the task's, or the host's. HOST is everything that is not the task's: the
+     * agent's turn taken by the environment (a signed-out agent, a spent quota, a killed turn, an operator's cancel) or a
+     * change set or trace the host could not capture. Only the first kind is the coding lane's, so the dispatch's page and
+     * card offer to see whether the lane is ready, never to explain the failure (#2530 review M2, #2531 review L1). NULL for
+     * a run that did not fail, a generation step, and a run recorded before it.
+     */
+    failureAttribution: z.enum(CodingRunFailureAttribution).systemEnum('CodingRunFailureAttribution').nullable(),
     /**
      * The conversation the dispatch was started from (#1454, Step 7), so the thread shows it as a
      * card. NULL for a dispatch started from the plan's next-task door or before conversations existed.
      */
     conversationId: z.string().min(1).isSummaryField().nullable(),
+    /**
+     * How the dispatch's RUN stands — the status of the actor execution the dispatch is (#2523).
+     *
+     * Every dispatch is one execution (#1359): a coding run on `application-coding.system`, a generation step
+     * on `application-build.system`. Its status is the one truthful answer to "did it work", for both
+     * executors. The phase cannot give it: a coding dispatch's phase resolves at ADMITTED, by design, so a run
+     * that has since completed, failed or is waiting on an answer still reads ADMITTED there. Every consumer
+     * that keyed a coding run's end on `phase === FINISHED` was asking a question no coding run could answer:
+     * the conversation's dispatch card never offered Accept, and Home never listed a coding run as settled.
+     */
+    runStatus: z.enum(FlowsActors_Status).systemEnum('FlowsActors_Status').isSummaryField(),
+    /** When the run ENDED. NULL while it is pending, running or waiting on an answer. */
+    runFinishedAt: z.date().isSummaryField().nullable(),
     /**
      * Whether the coding run's writes have been ACCEPTED — committed through the `accept` verb, or
-     * found already committed. NULL when there is nothing to accept: a generation step, a failed run,
-     * a run that wrote nothing, or a run older than the coding-run write register.
+     * found already committed.
+     *
+     * FALSE means exactly one thing: a coding run that COMPLETED, recorded writes, and has none committed
+     * yet — the state the `accept` verb addresses. NULL when there is nothing to accept NOW: a generation
+     * step, a run still running or waiting on an answer, a failed run, a run that wrote nothing, or a run
+     * older than the coding-run write register.
      */
     accepted: z.boolean().isSummaryField().nullable(),
 });
+/**
+ * One ATTEMPT at a build task (#2530): one actor execution, as the build's record reads it. A coding run, or a companion
+ * generation step (labels, migrations, translations).
+ */
+export const Workbench_BuildTaskAttempt_Schema = z.object({
+    /** The execution's own task id: the coding run's actor task, or the generation step's. */
+    runTaskId: z.string().min(1),
+    startedAt: z.date(),
+    settledAt: z.date().nullable(),
+    status: z.enum(FlowsActors_Status).systemEnum('FlowsActors_Status'),
+    /**
+     * A companion generation step (labels, migrations, translations) rather than a coding run. No agent ran, so its cost and
+     * tokens are what its own model calls were MEASURED at, and may be a floor (`spendIsFloor`) where some reported nothing.
+     */
+    generationStep: z.boolean(),
+    /**
+     * Refused by the host before it started (an admission refusal, a run a stopped process left selected). In the
+     * history, because it explains why nothing ran; counted by no figure, because it was no attempt of the task's.
+     */
+    refusedBeforeStart: z.boolean(),
+    /** Nothing ran: a host refusal, or admission refusing the task's own contract (which the budget does count). */
+    ranNothing: z.boolean(),
+    /** Whose failure a failed run was; null for a run that did not fail, and for a run recorded before the field. */
+    failureAttribution: z.enum(CodingRunFailureAttribution).systemEnum('CodingRunFailureAttribution').nullable(),
+    /** It failed while other runs were editing the tree, so the failure may be theirs. */
+    interferenceSuspected: z.boolean(),
+    /**
+     * Why the task was put back in the queue after this run, which then no longer held it; null when it was not. A person's
+     * reason, or the build wave's own when the run's product was lost to a sibling run editing the same file.
+     */
+    rearmReason: z.enum(BuildTaskRearmReason).systemEnum('BuildTaskRearmReason').nullable(),
+    /** What was fixed, as the re-arm recorded it; null when the run was not re-armed. */
+    rearmNote: z.string().min(1).nullable(),
+    /** Why it failed, verbatim; null when it did not. */
+    error: z.string().min(1).nullable(),
+    /**
+     * What the run cost, with its currency: what the agent reported for a coding run, what its model calls were measured at
+     * for a generation step (in one currency; a step that spent in several shows none). Null when nothing reported a cost —
+     * never read as zero.
+     */
+    costAmount: z.number().nullable(),
+    costCurrency: z.string().min(1).nullable(),
+    /** The cost and tokens are a FLOOR: a generation step some of whose model calls reported no usage. */
+    spendIsFloor: z.boolean(),
+    /**
+     * The tokens the run reported in all; null when it reported none. Mostly prompt-cache reads for a coding run, so a
+     * large figure is the agent re-reading its context, not that much new work.
+     */
+    totalTokens: z.number().int().min(0).nullable(),
+    /** Files the run itself changed; null when the run recorded none. */
+    filesChanged: z.number().int().nullable(),
+    /** The checks the run itself failed, by ref (a check already red when it started is not its failure, so not here). */
+    failedCheckRefs: z.array(z.string().min(1)),
+    /** Paths the run changed outside the task's declared scope: recorded, never refused. */
+    outOfScopePaths: z.array(z.string().min(1)),
+    /**
+     * The run COMPLETED and a sibling of its wave overwrote its product (#2210): which runs, which of the task's product
+     * files both changed, and whether the wave re-ran the task for it. Null for a run nobody overwrote. The case a person's
+     * re-arm answers once the wave's own re-runs are spent.
+     */
+    interference: z.object({
+        overlappingTaskRefs: z.array(z.string().min(1)),
+        contendedProductPaths: z.array(z.string().min(1)),
+        requeued: z.boolean(),
+    }).nullable(),
+    /*
+     * NOT carried: why the agent's turn ended (`max_tokens`, `refusal`), which is the agent's own vocabulary with no
+     * words here yet; the run's own page shows it.
+     */
+});
+/**
+ * What `wildo db diff --check` could tell the host about the resource model versus the accepted schema plan.
+ *
+ * THREE answers, not two. A boolean merged the two failures that lead to opposite places (found in review,
+ * 2026-09-13): DRIFTED means the migration step has work and must run first; UNANSWERABLE means the check did not
+ * report drift and did not pass — no accepted plan and an undeterminable store declaration, no built backend registry, a compiled model older than its
+ * sources (`assessCompiledModelCurrency`, #403: before it, a dead watcher's stale dist answered IN_SYNC and landed
+ * this step with drift on disk), a CLI that could not import
+ * it or could not be spawned, a timeout, a lockfile that fails strict parsing, or an ENGINE planner-contract
+ * mismatch (whose remedy is `wildo db generate --accept-planner-contract`, not a rebuild) — and
+ * running the step then only throws. Read as one "not in sync", an unanswerable check put a step that can
+ * only fail at the head of the build queue on every dispatch, so no other task could run.
+ *
+ * Only IN_SYNC ever lands the step: an unanswered question must not land a migration step either.
+ *
+ * Declared here rather than beside its producer (the companion's generation steps) because the workbench shows it on a
+ * step's record (#2530).
+ */
+export var SchemaPlanSyncState;
+(function (SchemaPlanSyncState) {
+    /** The model and the accepted plan agree: the migration step has landed. */
+    SchemaPlanSyncState["IN_SYNC"] = "in_sync";
+    /** The check ran and reported ungenerated changes: the migration step has work to do. */
+    SchemaPlanSyncState["DRIFTED"] = "drifted";
+    /** The check neither passed nor reported drift (see above for the causes); running the step now would refuse or fail. */
+    SchemaPlanSyncState["UNANSWERABLE"] = "unanswerable";
+})(SchemaPlanSyncState || (SchemaPlanSyncState = {}));
+/**
+ * What `wildo design-tokens validate` could tell the host about the stylesheet's generated block.
+ *
+ * Three answers, for the reason {@link SchemaPlanSyncState} has three: the command exits non-zero for a
+ * stale block AND for every could-not-ask failure (a config that does not load, a stylesheet with no
+ * markers, a CLI that cannot start or times out), and the two lead to opposite places. STALE means the
+ * `design-tokens` step has work; UNANSWERABLE means running it would refuse or fail the same way, so the
+ * dispatch host passes over it while other work is ready.
+ *
+ * Declared here for the reason {@link SchemaPlanSyncState} is (#2530).
+ */
+export var DesignTokenBlockState;
+(function (DesignTokenBlockState) {
+    /** The block is exactly what `generate` would write from the config. */
+    DesignTokenBlockState["CURRENT"] = "current";
+    /** The block differs from what `generate` would write: the step has work. */
+    DesignTokenBlockState["STALE"] = "stale";
+    /** The command neither confirmed nor refuted the block; running the step now would fail the same way. */
+    DesignTokenBlockState["UNANSWERABLE"] = "unanswerable";
+})(DesignTokenBlockState || (DesignTokenBlockState = {}));
+/**
+ * Does every module the brand step writes (the frontend's brand design, and the website's colours when a website is
+ * declared) say what the brand's visual tone now renders?
+ *
+ * Three answers, for the reason {@link DesignTokenBlockState} has three: STALE means the step has work and runs,
+ * UNANSWERABLE means the brand could not be read (the specifications do not evaluate, or this host has no
+ * introspection), and running the step then only throws, so the selector passes it over while other work is ready.
+ *
+ * Declared here for the reason {@link SchemaPlanSyncState} is (#2530).
+ */
+export var BrandDesignState;
+(function (BrandDesignState) {
+    /** Every module exists and equals the render of the brand's current visual tone. */
+    BrandDesignState["CURRENT"] = "current";
+    /** A module is absent or says something the brand no longer does. */
+    BrandDesignState["STALE"] = "stale";
+    /** The brand's visual tone could not be read, so currency cannot be decided either way. */
+    BrandDesignState["UNANSWERABLE"] = "unanswerable";
+})(BrandDesignState || (BrandDesignState = {}));
+/** A landing probe HEAD does not satisfy (#2530): what landing searched for, and whether the working tree has it. */
+export const Workbench_BuildTaskUnmetProbe_Schema = z.object({
+    /**
+     * The files the probe reads, and how they are read: ONE path is that file, committed (and declaring `declarations`
+     * when it names any); SEVERAL paths with `declarations` are candidates, any one of which may declare them; several with
+     * `keyPrefix` are the language packs, every committed one of which must carry a key under it. Empty for a shell probe,
+     * which reads the resolved shell rather than a fixed file (`shellSurface`, `shell`). The probe's KIND is the
+     * companion's (`BuildPlanTaskLandedProbeKind`): these fields are what it looks for, and between them say which kind.
+     */
+    paths: z.array(z.string().min(1)),
+    /**
+     * The symbols the probe looks for in those files; empty for a probe that asks only that a file be committed. WHERE in
+     * the file they must sit (a set, one call's arguments, a key at an object path, a list's entry) is the companion's
+     * probe relation and is not carried: its parameters are code locations the companion derives only when it probes, and
+     * no surface shows them, a run's included (#2531 review L4). A reader learns WHAT is missing here, not where it goes.
+     */
+    declarations: z.array(z.string().min(1)),
+    /** The key every committed label pack must carry one under (a website section's words); null for other probes. */
+    keyPrefix: z.string().min(1).nullable(),
+    /**
+     * The shell surface a placement probe reads — a `PlacementSurface` value of the specifications. A string declaring that
+     * vocabulary, so it reads `system_enums.PlacementSurface` like the enum, since this package does not depend on the
+     * specifications. Null for the probe that asks whether ANY surface carries a placement, and for every probe that reads
+     * files.
+     */
+    shellSurface: z.string().min(1).systemEnum('PlacementSurface').nullable(),
+    /** A shell probe's explanation: what the surface lacks, still carries, or could not be asked. Null for a file probe. */
+    shell: z.object({
+        /** Why the surface could not be read, verbatim: the probe is then unsatisfied without being a "no". */
+        unanswerable: z.string().min(1).nullable(),
+        /** Subjects the plan placed there that the surface does not carry. */
+        missing: z.array(z.string().min(1)),
+        /** Subjects the plan declined that the surface still carries. */
+        declinedButPresent: z.array(z.string().min(1)),
+        /** Files contributing the surface that are not committed as they are. */
+        uncommittedPaths: z.array(z.string().min(1)),
+    }).nullable(),
+    /**
+     * A REGISTRY probe's explanation (#2966): an agent, an approval gate, a work unit, a metered usage recording (#2305
+     * S5) or a retention binding, proven from what the backend registers, and a role a relationship confers (#2305 S6),
+     * proven from `wildo.saas.config.ts`. Null for every other probe. Kept apart from `shell`, which reads a surface: these read a registry, and
+     * a "declined" entry has no meaning here.
+     */
+    registered: z.object({
+        /** Why the registry could not be read, verbatim: the probe is then unsatisfied without being a "no". */
+        unanswerable: z.string().min(1).nullable(),
+        /**
+         * What the task's module does not register as planned, one entry per shortfall: WHY (worded from
+         * `system_enums.AgentWorkShortfallKind`), the ref it is about, and the planned and registered values where it compares
+         * them (for a refused gate, the engine's refusal, verbatim).
+         */
+        missing: z.array(z.object({
+            kind: z.enum(AgentWorkShortfallKind).systemEnum('AgentWorkShortfallKind'),
+            ref: z.string().min(1),
+            planned: z.string().min(1).nullable(),
+            registered: z.string().min(1).nullable(),
+        })),
+        /** Files where the product is written that are not committed as they are. */
+        uncommittedPaths: z.array(z.string().min(1)),
+    }).nullable(),
+    /**
+     * The working tree satisfies it: the product is written and not committed — an acceptance question. False: it is
+     * absent — a declaration or a work question. "Not landed" alone cannot tell the two apart.
+     */
+    satisfiedInWorkingTree: z.boolean(),
+});
+/**
+ * Everything the build knows about ONE task, in one row (#2530, from the companion's per-task record, #1521).
+ *
+ * The case it exists for: "not landed" hid three facts — never dispatched, dispatched and FAILED, dispatched,
+ * SUCCEEDED and unprovable — and they are three shapes here: no attempts; a failed attempt; a completed attempt with
+ * unmet probes. Its id IS the build-plan task row's id, so a task's detail reads its record by the id it already has;
+ * it is its own resource because reading attempts, classifying a stuck task and probing the tree is too much to pay on
+ * every row of the task list.
+ *
+ * The attempts are read from the actor plane by ONE listing per coding system, bounded far above a whole build's runs;
+ * `attemptsTruncated` says when that bound was met, so an early task's oldest runs may be missing and "never run" is not
+ * claimed.
+ */
+export const Workbench_BuildTaskRecord_Schema = z.object({
+    workbenchBuildTaskRecordId: z.string().min(1).isPrimaryKey().isSummaryField(),
+    /** The build-plan task this is the record of (the same id). */
+    workbenchBuildPlanTaskId: z.string().min(1).isForeignKey().isSummaryField(),
+    taskRef: z.string().min(1).isSummaryField(),
+    status: z.enum(WorkbenchBuildPlanTaskStatus).systemEnum('WorkbenchBuildPlanTaskStatus').isSummaryField(),
+    /**
+     * Attempts that count (every one but a host refusal before start). Which FAILED ones count against the attempt
+     * budget is the budget's own question (host failures and suspected interference are forgiven up to a bound); each
+     * attempt says what it needs for that, and a spent budget is `stuckReason` ATTEMPTS_EXHAUSTED, never re-derived here.
+     */
+    attemptCount: z.number().int().min(0).isSummaryField(),
+    /** Newest first. Empty: never dispatched (unless `attemptsTruncated`). */
+    attempts: z.array(Workbench_BuildTaskAttempt_Schema),
+    /** The attempt listing met its bound: the oldest attempts of an early task may be missing. */
+    attemptsTruncated: z.boolean(),
+    /** READY and passed over by dispatch: why, from the same classification the selector uses. */
+    stuckReason: z.enum(Workbench_BuildTaskStuckReason).systemEnum('Workbench_BuildTaskStuckReason').isSummaryField().nullable(),
+    /** `completed_awaiting_commit`: the files its run wrote that are not committed — what accepting it would commit. */
+    stuckUncommittedPaths: z.array(z.string().min(1)),
+    /** `parked_awaiting_answer`: the question its run is waiting on. */
+    stuckQuestion: z.string().min(1).nullable(),
+    /** `no_document_blueprint`: the governed document no blueprint defines. */
+    stuckDocumentRef: z.string().min(1).nullable(),
+    /** BLOCKED: the prerequisites that have not landed. */
+    waitingOnTaskRefs: z.array(z.string().min(1)),
+    /** Not landed and attempted: the probes HEAD does not satisfy. */
+    unmetProbes: z.array(Workbench_BuildTaskUnmetProbe_Schema),
+    /*
+     * A GENERATION STEP lands on something other than a file it writes, and when it has not, which of these three it is
+     * says whether running it again can help: the step's own state, null when it is current or is not that step.
+     */
+    /** The migration step: whether the model and the accepted schema plan agree. */
+    schemaPlanSyncState: z.enum(SchemaPlanSyncState).systemEnum('SchemaPlanSyncState').nullable(),
+    /** The design-tokens step: whether the stylesheet's generated block is what the config would generate. */
+    designTokenBlockState: z.enum(DesignTokenBlockState).systemEnum('DesignTokenBlockState').nullable(),
+    /** The brand-design step: whether the generated module says what the brand's visual tone renders. */
+    brandDesignState: z.enum(BrandDesignState).systemEnum('BrandDesignState').nullable(),
+    /**
+     * A generation step whose landing cannot be judged, and why, verbatim (#2504): today a labels plan that hides units
+     * the application owes. Named before the step's first run too, since it holds the step back from running. Null when
+     * nothing holds its landing.
+     */
+    landingBlockedBy: z.string().min(1).nullable(),
+    /*
+     * The follow-up tasks (#2496): what the host derived from a gap this task's latest completed run reported still unmet,
+     * and on a follow-up, the task whose gap derived it. By build-plan task row id, so each opens the task it names
+     * (#2652); `wildo context journey` prints the same two facts.
+     */
+    /** The follow-up tasks derived from this task's reported gaps; empty when none was derived. */
+    followUpTaskIds: z.array(z.string().min(1).isForeignKey()),
+    /** On a follow-up task: the task whose reported gap derived it; null on every other task. */
+    followUpOfTaskId: z.string().min(1).isForeignKey().nullable(),
+    /** LANDED with no product to prove: it ran, and nothing can show what it made. */
+    unverifiable: z.boolean(),
+    /** LANDED before any run of its own started: something else made its product, or the probe reads the wrong thing. */
+    landedBeforeAnyRun: z.boolean(),
+    /** Where the probe found that product, so a reader can see what it took for it; empty unless `landedBeforeAnyRun`. */
+    landedBeforeAnyRunPaths: z.array(z.string().min(1)),
+});
 /**
  * One playbook run SUSPENDED waiting on a person.
  *
@@ -944,6 +1398,43 @@ export var Workbench_PlaybookRunState;
      */
     Workbench_PlaybookRunState["AWAITING_ANSWER"] = "awaiting_answer";
 })(Workbench_PlaybookRunState || (Workbench_PlaybookRunState = {}));
+/**
+ * One child of a composite run's round (#2530): the playbook that ran in it, why it was on the table, what it landed and
+ * whether it failed — the record's own summary (`PlaybookRunChoreographyChildSummary`), with its measurement left on the
+ * run's record. A child that was itself a LANE is known by the rounds that name it as their lane.
+ */
+export const Workbench_PlaybookRunRoundChild_Schema = z.object({
+    playbookRef: z.string().min(1),
+    /** Why it was on the table, in the runtime's own sentence (a first run, a refresh and what moved, a re-opening). */
+    ranBecause: z.string().min(1).nullable(),
+    /** The specification files it landed, in landing order. Empty is a finding, not a gap. */
+    landed: z.array(z.string().min(1)),
+    /** Why it failed, bounded as the record keeps it; null when it did not. */
+    failure: z.string().min(1).nullable(),
+});
+/**
+ * One round of a composite run (#2530): the root's, or a nested lane's. FLAT rather than nested: a lane's rounds follow
+ * the round whose child ran the lane and name it (`parentRoundKey`, `lanePlaybookRef`), so a process map nests them as
+ * groups without a recursive contract, and every depth the record keeps reaches the row.
+ *
+ * The choreography's own stop reason (`PlaybookChoreographyStopReason`) is NOT here: it is a closed vocabulary of the
+ * runtime, which this package does not depend on, and a raw code would render as words nobody authored. Each round's
+ * `stopRationale` is the selector's own sentence for why that round ended the run; the reason code stays on the record.
+ */
+export const Workbench_PlaybookRunRound_Schema = z.object({
+    /** The round's place in the run: `3` for the root's third, `3/<lane playbook>/2` for the second round of that lane. */
+    roundKey: z.string().min(1),
+    /** The round whose child ran this lane; null for a round of the run itself. */
+    parentRoundKey: z.string().min(1).nullable(),
+    /** The child playbook whose lane this round belongs to; null for a round of the run itself. */
+    lanePlaybookRef: z.string().min(1).nullable(),
+    iteration: z.number().int().min(1),
+    /** The earlier round of the same lane that began from the very same input state: a lane spending without converging. */
+    sameInputStateAsIteration: z.number().int().min(1).nullable(),
+    /** Why the selector stopped after this round, in its own sentence; null when it went on. */
+    stopRationale: z.string().min(1).nullable(),
+    children: z.array(Workbench_PlaybookRunRoundChild_Schema),
+});
 /**
  * One playbook run, in whatever state it is in.
  *
@@ -1030,6 +1521,12 @@ export const Workbench_PlaybookRun_Schema = z.object({
     })).nullable(),
     /** Why the judge stayed silent, in its own words — a failed call, or an evaluation that never ran. */
     judgeSkipped: z.string().min(1).nullable(),
+    /**
+     * A COMPOSITE run's rounds, its own and every nested lane's, in run order (#2530), each with the children that ran in
+     * it — what a process map draws as rounds, then child runs. Null for a run of a single playbook, and for a run not
+     * settled yet (its rounds are on the record once it ends).
+     */
+    choreographyRounds: z.array(Workbench_PlaybookRunRound_Schema).nullable(),
 });
 export const Workbench_WaitingPlaybookRun_Schema = z.object({
     /** The run's own id, sanitized — run ids carry dots (see the playbook id note). */
@@ -1084,13 +1581,10 @@ export const Workbench_WaitingPlaybookRun_Schema = z.object({
     routedToUserId: z.string().min(1).isSummaryField().nullable(),
 });
 /**
- * One coding run PARKED on a question.
- *
- * It arrives inside the coding-agent status payload, which is a singleton and stays a companion
- * read. These do not: a parked question is identified by the task that parked on it, it persists
- * until somebody answers, and a queue of work waiting on a person is the last thing that should be
- * reachable only by reading a status blob.
+ * The coding lane's one row id. Named, because the workbench links to the row from where the lane's trouble shows (an
+ * attempt, a dispatch or a dispatch card the host failed, #2530) and the companion stamps it: two copies of the literal would be two ids.
  */
+export const WORKBENCH_CODING_LANE_STATUS_ROW_ID = 'coding-lane';
 /**
  * The coding lane's own posture — ONE row, always present.
  *
@@ -1113,7 +1607,7 @@ export const Workbench_WaitingPlaybookRun_Schema = z.object({
  * outstanding — which is why the parked queue has to be read beside it.
  */
 export const Workbench_CodingLaneStatus_Schema = z.object({
-    /** One row, one id. The projection stamps a constant: there is exactly one coding lane. */
+    /** One row, one id ({@link WORKBENCH_CODING_LANE_STATUS_ROW_ID}): there is exactly one coding lane. */
     workbenchCodingLaneStatusId: z.string().min(1).isPrimaryKey().isSummaryField(),
     /** Every declared coding agent resolves in the registry. NOT a claim that the transport works. */
     codingAgentRegistered: z.boolean().isSummaryField(),
@@ -1176,6 +1670,14 @@ export var Workbench_ParkedCodingQuestionOptionRef;
 })(Workbench_ParkedCodingQuestionOptionRef || (Workbench_ParkedCodingQuestionOptionRef = {}));
 /** The single field a parked run asks: the agent's own question, verbatim. */
 export const WORKBENCH_PARKED_CODING_QUESTION_FIELD_REF = 'answer';
+/**
+ * One coding run PARKED on a question.
+ *
+ * It arrives inside the coding-agent status payload, which is a singleton and stays a companion
+ * read. These do not: a parked question is identified by the task that parked on it, it persists
+ * until somebody answers, and a queue of work waiting on a person is the last thing that should be
+ * reachable only by reading a status blob.
+ */
 export const Workbench_ParkedCodingQuestion_Schema = z.object({
     /** The parked task's id, sanitized. */
     workbenchParkedCodingQuestionId: z.string().min(1).isPrimaryKey().isSummaryField(),
@@ -1736,7 +2238,10 @@ export var ApplicationSecretStanding;
     ApplicationSecretStanding["NEEDED"] = "needed";
     /** It has a value in this environment, and something reads it. */
     ApplicationSecretStanding["SET"] = "set";
-    /** Unset, and nothing waits for it: an optional key, or a capability another provider already serves. */
+    /**
+     * Unset, and nothing waits for it: an optional key, or a capability another provider already serves, ready, in every
+     * runtime that would use this key for it (a provider ready in the backend serves nothing to the companion, #2985).
+     */
     ApplicationSecretStanding["AVAILABLE"] = "available";
     /**
      * It has a value, and nothing CONSUMES it: a provider key no provider declares, a system-of-record key
@@ -1854,7 +2359,11 @@ export const Workbench_ApplicationSecret_Schema = z.object({
     ownerRef: z.string().min(1).nullable().isSummaryField(),
     /** Its owner's own description of it, when it has one. */
     description: z.string().nullable(),
-    /** The enabled capabilities a provider serves for this application — why the secret is needed. Empty for the other kinds. */
+    /**
+     * The enabled capabilities this secret serves — why it is needed: those of the provider arms that READ it, not every
+     * capability its provider serves (#2978). Empty for a key no capability-serving arm reads (a sign-in client secret)
+     * and for the other kinds.
+     */
     capabilities: z.array(z.enum(EngineCapability).systemEnum('EngineCapability')),
     /**
      * The runtimes that RECEIVE it in their environment — the ones a change regenerates and restarts: `backend`,