fix(plugin-chatbot): keep @objectstack/spec symbols out of the published build-progress typings (objectui#11988)

Naming BuildProgressPhase in ChatbotEnhanced's exported interface put an
@objectstack/spec/ai reference into the published .d.ts that the package's
^17.0.0 floor cannot carry (check:spec-floors: floor-too-low, needs
^17.5.0). The exported phase union is spelled out instead, and a
compile-time test holds it equal to the spec's BuildProgressPhase in both
directions; the type-only spec import stays internal to mapMessages and is
erased from the typings.

Claude-Session: https://claude.ai/code/session_01CGZy1BGCjdN5cXqL9cnvB8
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/11988-build-verify-receiver.md

@@ -9,6 +9,6 @@ After `apply_blueprint` finishes, cloud's agent loop reports its verification ho
 
 - **The tree and the verification part are read apart, by part id.** The `build-verify` part never displaces the tree, whichever order the two parts arrive in. A message that carries only the tree maps and renders exactly as before.
 - **The build panel shows a verification line under the tree.** It reads "Checking the change… step N" while a hop runs, with the hop's tool name as its tooltip, and "Checked the change" once the `done` frame arrives. A `build-verify` part on a message that has no build tree is not drawn as a tree.
-- **Phases are read against the spec's vocabulary.** The receiver reads `BUILD_PROGRESS_PHASES` and `BUILD_PROGRESS_FRAME_TYPE` from `@objectstack/spec/ai` instead of restating them. A phase outside that vocabulary, or a frame without one, is now `unknown` and shows as a warning line ("Unknown build phase") on the tree header or on the verification line. It is no longer coerced to `structure`.
-- **Type change.** `ChatBuildProgress.phase`, reached through `ChatMessage['buildProgress']`, widens from `'structure' | 'data' | 'done'` to the spec's `BuildProgressPhase` plus `'unknown'`, and `ChatBuildProgress` gains an optional `verify` member: `{ phase, hop?, tool? }`.
+- **Phases are read against the spec's vocabulary.** The receiver's phase table and frame type are typed by `@objectstack/spec/ai`'s own `BuildProgressPhase` and `BUILD_PROGRESS_FRAME_TYPE`, so a phase the spec adds or drops fails the type check here instead of drifting. The spec's runtime module is not imported, because it would put its whole AI schema module on the console's first load. A phase outside the vocabulary, or a frame without one, is now `unknown` and shows as a warning line ("Unknown build phase") on the tree header or on the verification line. It is no longer coerced to `structure`.
+- **Type change.** `ChatBuildProgress.phase`, reached through `ChatMessage['buildProgress']`, widens from `'structure' | 'data' | 'done'` to `'structure' | 'data' | 'verify' | 'done' | 'unknown'`: the spec's phase vocabulary plus `'unknown'`, held equal to the spec's union by a compile-time test. `ChatBuildProgress` also gains an optional `verify` member, `{ phase, hop?, tool? }`. The published typings name no new `@objectstack/spec` symbol, so the package's spec range is unchanged.
 - **New language-pack keys, in all ten packs:** `chatbot.build.verifying`, `chatbot.build.verifyStep`, `chatbot.build.verified` and `chatbot.build.unknownPhase`.

packages/plugin-chatbot/src/ChatbotEnhanced.tsx

@@ -23,7 +23,6 @@ import { SchemaRenderer } from '@object-ui/react';
 import { useObjectTranslation, useSafeTranslate } from '@object-ui/i18n';
 import { AlertCircle, ArrowRight, Copy, Check, RefreshCw, CornerDownLeft, Bot, Eye, GitCompareArrows, Rocket, Clock3, CheckCircle2, XCircle, Loader2, ShieldCheck, TriangleAlert, ClipboardList, HelpCircle, Table2, WifiOff, Sparkles, Hourglass } from 'lucide-react';
 import type { ChatStatus } from 'ai';
-import type { BuildProgressPhase } from '@objectstack/spec/ai';
 import {
   humanizeToolName,
   isRateLimitError,
@@ -158,15 +157,20 @@ export interface ChatChart {
   series: Array<{ dataKey: string; label?: string }>;
 }
 
+/**
+ * A build-progress frame's phase: `@objectstack/spec/ai`'s closed
+ * `BuildProgressPhase` vocabulary, plus `unknown` for a value outside it, which
+ * is surfaced as a warning — never as "Building" (objectui#11988). Spelled out
+ * rather than imported so the published typings need no newer spec floor;
+ * `buildVerify-11988.test.tsx` asserts at compile time that it equals the
+ * spec's union, both ways.
+ */
+type ChatBuildPhase = 'structure' | 'data' | 'verify' | 'done' | 'unknown';
+
 /** A reconciled snapshot of an in-flight app build (apply_blueprint). */
 export interface ChatBuildProgress {
-  /**
-   * Coarse phase, from `@objectstack/spec/ai`'s closed vocabulary: drafting
-   * structure, generating sample data, or finished. `unknown` is a value
-   * outside that vocabulary, surfaced as a warning — never as "Building"
-   * (objectui#11988).
-   */
-  phase: BuildProgressPhase | 'unknown';
+  /** Coarse phase: drafting structure, generating sample data, or finished. */
+  phase: ChatBuildPhase;
   /** Human label for the app being built (for the panel header). */
   appLabel?: string;
   /** Artifacts drafted so far, cumulative. */
@@ -187,7 +191,7 @@ export interface ChatBuildProgress {
    * beside the tree (objectui#11988): `verify` while a hop runs, `done` once
    * the loop exits. `hop` and `tool` are the spec frame's own fields.
    */
-  verify?: { phase: BuildProgressPhase | 'unknown'; hop?: number; tool?: string };
+  verify?: { phase: ChatBuildPhase; hop?: number; tool?: string };
 }
 
 /**

packages/plugin-chatbot/src/__tests__/buildVerify-11988.test.tsx

@@ -21,11 +21,16 @@
 import '@testing-library/jest-dom/vitest';
 import { describe, it, expect, vi, afterEach } from 'vitest';
 import { render, screen, cleanup } from '@testing-library/react';
-import { BUILD_PROGRESS_PHASES } from '@objectstack/spec/ai';
+import { BUILD_PROGRESS_PHASES, type BuildProgressPhase } from '@objectstack/spec/ai';
 import { I18nProvider } from '@object-ui/i18n';
-import { ChatbotEnhanced } from '../ChatbotEnhanced';
+import { ChatbotEnhanced, type ChatBuildProgress } from '../ChatbotEnhanced';
 import { uiMessageToChatMessage } from '../mapMessages';
 
+type Assert<T extends true> = T;
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
+  ? true
+  : false;
+
 const ITEMS = [
   { type: 'object', name: 'customer' },
   { type: 'view', name: 'customer.list' },
@@ -57,6 +62,18 @@ function renderIn(language: string, parts: Array<Record<string, unknown>>) {
 
 afterEach(cleanup);
 
+describe('the published phase union IS the spec vocabulary plus `unknown` (objectui#11988)', () => {
+  it('is pinned at compile time, in both directions', () => {
+    // A `tsc` error, not a runtime failure: compiled by this package's
+    // `tsconfig.test.json`. A phase the spec adds or drops turns it red.
+    type _TreePhaseIsSpec = Assert<Equal<Exclude<ChatBuildProgress['phase'], 'unknown'>, BuildProgressPhase>>;
+    type _VerifyPhaseIsSpec = Assert<
+      Equal<Exclude<NonNullable<ChatBuildProgress['verify']>['phase'], 'unknown'>, BuildProgressPhase>
+    >;
+    expect(true).toBe(true);
+  });
+});
+
 describe('the receiver keeps the tree and the build-verify part apart (objectui#11988)', () => {
   it('a verify hop never displaces the finished tree', () => {
     const out = map([TREE, verifyPart({ phase: 'verify', hop: 1, tool: 'verify_build' })]);

packages/plugin-chatbot/src/mapMessages.ts

@@ -826,14 +826,16 @@ function extractSources(parts: AnyPart[]): ChatSource[] | undefined {
 
 /**
  * The build-progress frame vocabulary of `@objectstack/spec/ai`, read through
- * its TYPES (objectui#11988). Both tables are typed by the spec's own
+ * its TYPES (objectui#11988). Both constants are typed by the spec's own
  * declarations, so the compiler refuses a value the spec does not declare and,
  * for the phases, requires a row for every phase it does: neither can drift
  * from the vocabulary. The spec's runtime `BUILD_PROGRESS_PHASES` is not
  * imported: its module does not tree-shake, and a value import of it moved the
  * console's eager closure about 27 KB gzipped over budget (a one-time reading
- * of `pnpm check:eager-closure` against `fff07fbba`, objectui#11988). The test
- * beside the panel reads the runtime array and pins every member.
+ * of `pnpm check:eager-closure` against `fff07fbba`, objectui#11988). The
+ * type-only import is erased from the published typings, so it asks nothing of
+ * the package's spec floor. `buildVerify-11988.test.tsx` reads the runtime
+ * array and pins every member.
  */
 const BUILD_FRAME_TYPE: typeof BUILD_PROGRESS_FRAME_TYPE = 'data-build-progress';
 const BUILD_PHASES: Record<BuildProgressPhase, true> = { structure: true, data: true, verify: true, done: true };