spec(ai): declare the closed build-progress PHASE vocabulary the agent loop emits during post-apply verification

.changeset/build-progress-phase-vocabulary.md

@@ -0,0 +1,31 @@
+---
+'@objectstack/spec': minor
+---
+
+**Declare the build-progress PHASE vocabulary on `@objectstack/spec/ai`.**
+
+The `data-build-progress` stream frame has shipped as prose only: `AIToolContext.onProgress`
+documents the channel and its example carries a `phase`, but nothing ever declared which
+phases exist. Consumers filled that gap by guessing, and a guess here is not merely
+unlabelled — the objectui chat panel coerces any value it does not recognise to `structure`,
+which renders a "still building" spinner, so a build turn that has finished and moved on to
+verifying itself keeps claiming to be building.
+
+New exports (additive; nothing removed or renamed):
+
+- `BUILD_PROGRESS_PHASES` / `BuildProgressPhaseSchema` / `BuildProgressPhase` — the CLOSED
+  phase vocabulary: `structure`, `data`, `verify`, `done`, in lifecycle order. An
+  out-of-vocabulary value is refused, and the refusal names the accepted set.
+- `BuildProgressFrameSchema` / `BuildProgressFrame` — the frame's FLOOR: a required `phase`
+  plus an optional `hop` (which post-apply verification hop) and `tool` (the tool that hop is
+  running). Deliberately loose, not strict: the presentation fields the chat panel already
+  reads ride the same frame and belong to it, so a strict schema here would refuse every
+  frame shipping today.
+- `BUILD_PROGRESS_FRAME_TYPE` — `'data-build-progress'`, the one literal both ends select on.
+
+Producers emit these frames from the agent loop rather than from the applying tool: a tool's
+`ctx.onProgress` handle dies when the tool returns, and the verification window opens after
+it does. Consumers should compare phases by value and treat every phase as optional — a turn
+that seeds no sample data never reports `data`.
+
+Clause-②: yes (widening)

content/docs/getting-started/quick-reference.mdx

@@ -108,7 +108,7 @@ Runtime environment, logging, jobs, caching, and observability.
 | **[Translation](/docs/references/system/translation)** | `translation.zod.ts` | Translation | i18n support |
 | **[Worker](/docs/references/system/worker)** | `worker.zod.ts` | Worker | Background workers |
 
-## AI Protocol (11 of 11 schemas)
+## AI Protocol (11 of 12 schemas)
 
 AI/ML capabilities - agents, skills, tools, MCP exposure, RAG, and cost tracking.
 

content/docs/references/ai/build-progress.mdx

@@ -0,0 +1,83 @@
+---
+title: Build Progress
+description: Build Progress protocol schemas
+---
+
+{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
+
+Build-progress PHASE vocabulary for the `data-build-progress` stream frame
+(cloud#2172 ruling A).
+
+## Producer
+
+The cloud AI-studio **agent loop** — deliberately not the tool it just ran.
+A build turn applies its change through `apply_blueprint` / `apply_edit` and
+then keeps working: the loop spends a further POST-APPLY VERIFICATION window
+re-reading and re-seeding what it wrote (measured on cloud#1838: 111 seconds
+and 9 tool calls *after* `apply_blueprint` returned, one of them the
+registered `verify_build` tool — see `PLATFORM_TOOLS_BY_PACKAGE` in
+`../system/constants/platform-tool-names`). A tool's own `ctx.onProgress`
+handle dies when the tool returns, so a frame emitted in that window can only
+come from the loop. WHERE in the loop it is emitted is cloud#2172's decision,
+not this module's; what such a frame may SAY is declared here.
+
+## Consumer
+
+The objectui chat panel — `extractBuildProgress` in
+`packages/plugin-chatbot/src/mapMessages.ts`, which lifts the reconciled part
+onto `ChatBuildProgress` for the build panel in `ChatbotEnhanced.tsx`. That
+reader recognises a fixed set and coerces everything else to `'structure'`,
+which renders a "still building" spinner. So an UNDECLARED phase is not
+merely unlabelled — it reads as the wrong phase, and the user watches a
+build that finished two minutes ago still claim to be building
+(objectui#7388). The panel's per-phase COPY is objectui's to choose; this
+module fixes only the set of values it must be able to tell apart.
+
+## Channel
+
+Unchanged: the `data-`-prefixed custom part described on
+`AIToolContext.onProgress` in `../contracts/ai-service`, reconciled in place
+under a stable part id. This module adds the vocabulary that prose has always
+assumed and never declared; it moves no transport and renames nothing.
+
+<Callout type="info">
+**Source:** `packages/spec/src/ai/build-progress.zod.ts`
+</Callout>
+
+## TypeScript Usage
+
+```typescript
+import { BuildProgressFrameSchema, BuildProgressPhaseSchema } from '@objectstack/spec/ai';
+import type { BuildProgressFrame, BuildProgressPhase } from '@objectstack/spec/ai';
+
+// Validate data
+const result = BuildProgressFrameSchema.parse(data);
+```
+
+---
+
+## BuildProgressFrame
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **phase** | `Enum<'structure' \| 'data' \| 'verify' \| 'done'>` | ✅ | Build-turn phase this frame reports |
+| **hop** | `integer` | optional | Post-apply verification hop this frame reports |
+| **tool** | `string` | optional | Name of the tool the current hop is running |
+
+
+---
+
+## BuildProgressPhase
+
+### Allowed Values
+
+* `structure`
+* `data`
+* `verify`
+* `done`
+
+
+---
+

content/docs/references/ai/index.mdx

@@ -9,6 +9,7 @@ This section contains all protocol schemas for the ai layer of ObjectStack.
 
 <Cards>
   <Card href="/docs/references/ai/agent" title="Agent" description="Source: packages/spec/src/ai/agent.zod.ts" />
+  <Card href="/docs/references/ai/build-progress" title="Build Progress" description="Source: packages/spec/src/ai/build-progress.zod.ts" />
   <Card href="/docs/references/ai/conversation" title="Conversation" description="Source: packages/spec/src/ai/conversation.zod.ts" />
   <Card href="/docs/references/ai/embedding" title="Embedding" description="Source: packages/spec/src/ai/embedding.zod.ts" />
   <Card href="/docs/references/ai/knowledge-document" title="Knowledge Document" description="Source: packages/spec/src/ai/knowledge-document.zod.ts" />

content/docs/references/ai/meta.json

@@ -14,6 +14,8 @@
     "---Models & Runtime---",
     "conversation",
     "model-registry",
-    "usage"
+    "usage",
+    "---More---",
+    "build-progress"
   ]
 }

content/docs/references/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Protocol Reference
-description: Every schema published by @objectstack/spec — 1525 schemas across 14 protocol modules
+description: Every schema published by @objectstack/spec — 1527 schemas across 14 protocol modules
 ---
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
@@ -19,7 +19,7 @@ counts are sums of the rows they head. Regenerate with
 
 | Module | Pages | Schemas | Description |
 | :--- | ---: | ---: | :--- |
-| [AI Protocol](/docs/references/ai) | 11 | 66 | Agents, tools, skills, RAG and knowledge sources, model registry, conversations. |
+| [AI Protocol](/docs/references/ai) | 12 | 68 | Agents, tools, skills, RAG and knowledge sources, model registry, conversations. |
 | [API Protocol](/docs/references/api) | 31 | 440 | REST contracts, endpoints, routing, realtime, batch, discovery. |
 | [Automation Protocol](/docs/references/automation) | 14 | 74 | Flows and their nodes, approvals, ETL pipelines, webhooks, state machines, execution records. |
 | [Data Protocol](/docs/references/data) | 29 | 173 | Objects, fields, queries, filters, datasources and drivers — the ObjectQL layer. |
@@ -33,19 +33,20 @@ counts are sums of the rows they head. Regenerate with
 | [Studio Protocol](/docs/references/studio) | 3 | 35 | Studio designer metadata — the authoring surfaces for the protocols above. |
 | [System Protocol](/docs/references/system) | 33 | 272 | The runtime environment — logging, jobs, cache, metrics, notifications, i18n and compliance. |
 | [UI Protocol](/docs/references/ui) | 16 | 156 | Apps, pages, views, dashboards, reports, actions and themes — the ObjectUI layer. |
-| **Total** | **193** | **1525** | 14 protocol modules |
+| **Total** | **194** | **1527** | 14 protocol modules |
 
 ---
 
 ## AI Protocol
 
-**Source:** `packages/spec/src/ai/` · **Import:** `@objectstack/spec/ai` · **11 pages, 66 schemas**
+**Source:** `packages/spec/src/ai/` · **Import:** `@objectstack/spec/ai` · **12 pages, 68 schemas**
 
 Agents, tools, skills, RAG and knowledge sources, model registry, conversations.
 
 | File | Schemas |
 | :--- | :--- |
 | [`agent.zod.ts`](/docs/references/ai/agent) | `AIModelConfig`, `Agent`, `StructuredOutputConfig`, `StructuredOutputFormat`, `TransformPipelineStep` |
+| [`build-progress.zod.ts`](/docs/references/ai/build-progress) | `BuildProgressFrame`, `BuildProgressPhase` |
 | [`conversation.zod.ts`](/docs/references/ai/conversation) | `CodeContent`, `ConversationAnalytics`, `ConversationContext`, `ConversationMessage`, `ConversationSession`, `ConversationSummary`, `FileContent`, `FunctionCall`, `ImageContent`, `MessageContent`, `MessageContentType`, `MessagePruningEvent`, `MessageRole`, `TextContent`, `TokenBudgetConfig`, `TokenBudgetStrategy`, `TokenUsageStats`, `ToolCall` |
 | [`embedding.zod.ts`](/docs/references/ai/embedding) | `EmbeddingModel`, `VectorStore`, `VectorStoreProvider` |
 | [`knowledge-document.zod.ts`](/docs/references/ai/knowledge-document) | `KnowledgeChunk`, `KnowledgeDocument`, `KnowledgeHit` |

docs/audits/2026-07-unknown-key-strictness-ledger.counts.md

@@ -256,7 +256,7 @@ directory rather than per file.
 
 | Dir | Sites |
 |---|---|
-| `ai/` | 77 |
+| `ai/` | 78 |
 | `api/` | 451 |
 | `identity/` | 32 |
 | `integration/` | 8 |

packages/spec/api-surface/ai.json

@@ -8,6 +8,8 @@
     "Agent (type)",
     "AgentParsed (type)",
     "AgentSchema (const)",
+    "BUILD_PROGRESS_FRAME_TYPE (const)",
+    "BUILD_PROGRESS_PHASES (const)",
     "BlueprintApp (type)",
     "BlueprintAppParsed (type)",
     "BlueprintAppSchema (const)",
@@ -31,6 +33,10 @@
     "BlueprintViewSchema (const)",
     "BlueprintWidgetCondition (type)",
     "BlueprintWidgetConditionSchema (const)",
+    "BuildProgressFrame (type)",
+    "BuildProgressFrameSchema (const)",
+    "BuildProgressPhase (type)",
+    "BuildProgressPhaseSchema (const)",
     "CodeContentSchema (const)",
     "ConversationAnalytics (type)",
     "ConversationAnalyticsParsed (type)",

packages/spec/authorable-surface/ai.json

@@ -84,6 +84,9 @@
     "ai/BlueprintWidgetCondition:field",
     "ai/BlueprintWidgetCondition:op",
     "ai/BlueprintWidgetCondition:value",
+    "ai/BuildProgressFrame:hop",
+    "ai/BuildProgressFrame:phase",
+    "ai/BuildProgressFrame:tool",
     "ai/CodeContent:language",
     "ai/CodeContent:metadata",
     "ai/CodeContent:text",

packages/spec/declaration-map/ai.json

@@ -27,6 +27,10 @@
     "BlueprintViewSchema": "ai/BlueprintView",
     "BlueprintWidgetCondition": "ai/BlueprintWidgetCondition",
     "BlueprintWidgetConditionSchema": "ai/BlueprintWidgetCondition",
+    "BuildProgressFrame": "ai/BuildProgressFrame",
+    "BuildProgressFrameSchema": "ai/BuildProgressFrame",
+    "BuildProgressPhase": "ai/BuildProgressPhase",
+    "BuildProgressPhaseSchema": "ai/BuildProgressPhase",
     "CodeContentSchema": "ai/CodeContent",
     "ConversationAnalytics": "ai/ConversationAnalytics",
     "ConversationAnalyticsSchema": "ai/ConversationAnalytics",

packages/spec/export-origins/ai.json

@@ -8,6 +8,8 @@
     "Agent": "src/ai/agent.zod.ts#Agent (type)",
     "AgentParsed": "src/ai/agent.zod.ts#AgentParsed (type)",
     "AgentSchema": "src/ai/agent.zod.ts#AgentSchema (const)",
+    "BUILD_PROGRESS_FRAME_TYPE": "src/ai/build-progress.zod.ts#BUILD_PROGRESS_FRAME_TYPE (const)",
+    "BUILD_PROGRESS_PHASES": "src/ai/build-progress.zod.ts#BUILD_PROGRESS_PHASES (const)",
     "BlueprintApp": "src/ai/solution-blueprint.zod.ts#BlueprintApp (type)",
     "BlueprintAppParsed": "src/ai/solution-blueprint.zod.ts#BlueprintAppParsed (type)",
     "BlueprintAppSchema": "src/ai/solution-blueprint.zod.ts#BlueprintAppSchema (const)",
@@ -31,6 +33,10 @@
     "BlueprintViewSchema": "src/ai/solution-blueprint.zod.ts#BlueprintViewSchema (const)",
     "BlueprintWidgetCondition": "src/ai/solution-blueprint.zod.ts#BlueprintWidgetCondition (type)",
     "BlueprintWidgetConditionSchema": "src/ai/solution-blueprint.zod.ts#BlueprintWidgetConditionSchema (const)",
+    "BuildProgressFrame": "src/ai/build-progress.zod.ts#BuildProgressFrame (type)",
+    "BuildProgressFrameSchema": "src/ai/build-progress.zod.ts#BuildProgressFrameSchema (const)",
+    "BuildProgressPhase": "src/ai/build-progress.zod.ts#BuildProgressPhase (type)",
+    "BuildProgressPhaseSchema": "src/ai/build-progress.zod.ts#BuildProgressPhaseSchema (const)",
     "CodeContentSchema": "src/ai/conversation.zod.ts#CodeContentSchema (const)",
     "ConversationAnalytics": "src/ai/conversation.zod.ts#ConversationAnalytics (type)",
     "ConversationAnalyticsParsed": "src/ai/conversation.zod.ts#ConversationAnalyticsParsed (type)",

packages/spec/json-schema.manifest/ai.json

@@ -15,6 +15,8 @@
     "ai/BlueprintSummaryOperations",
     "ai/BlueprintView",
     "ai/BlueprintWidgetCondition",
+    "ai/BuildProgressFrame",
+    "ai/BuildProgressPhase",
     "ai/CodeContent",
     "ai/ConversationAnalytics",
     "ai/ConversationContext",

packages/spec/llms.txt

@@ -77,7 +77,7 @@ const query = {
 
 ---
 
-## 3. Schema Inventory by Domain (200 schemas)
+## 3. Schema Inventory by Domain (201 schemas)
 
 Counted as `*.zod.ts` modules under `packages/spec/src/<domain>/` — the sources
 that ship in this tarball (`files` includes `src/**/*.zod.ts`), so every number
@@ -92,7 +92,7 @@ here is verifiable from the installed package.
 | ui | 18 | View, App, Action, Dashboard, Page, Chart, Component, Animation |
 | automation | 14 | Flow, Approval, BPMN Interop, Control Flow, State Machine, Webhook, Schedule Organization |
 | shared | 15 | Enums, HTTP, Identifiers, Mapping, Metadata Types, Connector Auth, Retry Policy, Value Domain, Epoch Instant (EpochMs), Duration (DurationMs / DurationSeconds) |
-| ai | 11 | Agent, Conversation, Knowledge Source/Document, Model Registry, MCP, Skill, Tool |
+| ai | 12 | Agent, Build Progress, Conversation, Knowledge Source/Document, Model Registry, MCP, Skill, Tool |
 | identity | 5 | Identity, Organization, Position, SCIM, Eval User |
 | marketplace | 4 | Marketplace, Package, Package Version, Template Manifest |
 | security | 4 | Permission, RLS, Sharing, Explain |