@@ -0,0 +1,182 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Pin for the build-progress PHASE vocabulary (cloud#2172 ruling A).
+ *
+ * What is actually at stake here is not "does zod reject a bad string" — it is
+ * that this vocabulary is CLOSED and that its refusal is LOUD. objectui#7388
+ * measured the cost of the alternative: the consumer's reader coerces any
+ * value it does not recognise to `'structure'`, so a phase nobody declared
+ * renders as a "still building" spinner for the 111 seconds the build spends
+ * being verified after it finished. A refusal that merely throws leaves the
+ * next author guessing; a refusal that names the accepted set tells them.
+ *
+ * So the refusal leg asserts the ENVELOPE, not the throw: zod 4 answers an
+ * out-of-vocabulary enum value with `invalid_value` and carries the full
+ * accepted set on the issue. ⛔ A bare `expect(...).toThrow()` here would stay
+ * green against a schema that had degraded to a bare `z.string()` with a
+ * refinement, which is exactly the degradation worth catching.
+ *
+ * The membership leg is the closed-enum pin. Each member was measured against
+ * a real end of the channel (provenance is recorded per member on
+ * `BUILD_PROGRESS_PHASES` in the source), so this array moving is a claim that
+ * someone re-measured — not an edit to wave through.
+ */
+
+import { describe, it, expect } from 'vitest';
+
+import {
+  BUILD_PROGRESS_PHASES,
+  BUILD_PROGRESS_FRAME_TYPE,
+  BuildProgressPhaseSchema,
+  BuildProgressFrameSchema,
+  type BuildProgressPhase,
+} from './build-progress.zod';
+
+/**
+ * The phases objectui's reader discriminates TODAY
+ * (`packages/plugin-chatbot/src/mapMessages.ts` `extractBuildProgress`, and the
+ * `ChatBuildProgress['phase']` union in `ChatbotEnhanced.tsx`). Declaring
+ * `verify` must not disturb the inherited three — this is the control that has
+ * to keep moving, not a restatement of the vocabulary under test.
+ */
+const PHASES_THE_CONSUMER_ALREADY_RENDERS = ['structure', 'data', 'done'] as const;
+
+describe('BUILD_PROGRESS_PHASES (closed membership)', () => {
+  it('is exactly the measured vocabulary, in lifecycle order', () => {
+    expect(BUILD_PROGRESS_PHASES).toEqual(['structure', 'data', 'verify', 'done']);
+  });
+
+  it('still contains every phase the objectui reader already discriminates', () => {
+    for (const phase of PHASES_THE_CONSUMER_ALREADY_RENDERS) {
+      expect(BUILD_PROGRESS_PHASES).toContain(phase);
+    }
+  });
+
+  it('names the post-apply verification phase the card exists to declare', () => {
+    expect(BUILD_PROGRESS_PHASES).toContain('verify');
+  });
+});
+
+describe('BuildProgressPhaseSchema', () => {
+  it('parses every declared phase', () => {
+    for (const phase of BUILD_PROGRESS_PHASES) {
+      const result = BuildProgressPhaseSchema.safeParse(phase);
+      expect(result.success).toBe(true);
+      expect(result.success && result.data).toBe(phase);
+    }
+  });
+
+  it('REFUSES an undeclared phase, and the refusal names the accepted set', () => {
+    const result = BuildProgressPhaseSchema.safeParse('rebuilding');
+
+    expect(result.success).toBe(false);
+    if (result.success) throw new Error('unreachable: an undeclared phase parsed');
+
+    const [issue] = result.error.issues;
+    expect(result.error.issues).toHaveLength(1);
+    expect(issue.code).toBe('invalid_value');
+    // The loud half: the author is told what WAS allowed, not merely that they
+    // were wrong. Compared against the exported vocabulary so the two cannot
+    // drift apart silently.
+    expect((issue as { values?: readonly unknown[] }).values).toEqual([...BUILD_PROGRESS_PHASES]);
+  });
+
+  it('REFUSES the neighbouring vocabulary of the sibling blueprint-progress frame', () => {
+    // `data-blueprint-progress` is a DIFFERENT channel with its own phases
+    // (`designing` / `done`). Folding its vocabulary in here would be the
+    // "one enum for two frames" mistake; `designing` must not parse.
+    expect(BuildProgressPhaseSchema.safeParse('designing').success).toBe(false);
+  });
+
+  it('REFUSES a non-string', () => {
+    expect(BuildProgressPhaseSchema.safeParse(3).success).toBe(false);
+    expect(BuildProgressPhaseSchema.safeParse(undefined).success).toBe(false);
+  });
+});
+
+describe('BUILD_PROGRESS_FRAME_TYPE', () => {
+  it('is the literal both ends select on', () => {
+    // objectui selects parts with `p.type === 'data-build-progress'`; the
+    // `data-` prefix is what makes it a custom data part at all.
+    expect(BUILD_PROGRESS_FRAME_TYPE).toBe('data-build-progress');
+    expect(BUILD_PROGRESS_FRAME_TYPE.startsWith('data-')).toBe(true);
+  });
+});
+
+describe('BuildProgressFrameSchema', () => {
+  it('parses a frame carrying only the required phase', () => {
+    const result = BuildProgressFrameSchema.safeParse({ phase: 'verify' });
+    expect(result.success).toBe(true);
+    expect(result.success && result.data.phase).toBe('verify');
+    expect(result.success && result.data.hop).toBeUndefined();
+    expect(result.success && result.data.tool).toBeUndefined();
+  });
+
+  it('parses a frame carrying both optional fields', () => {
+    const result = BuildProgressFrameSchema.safeParse({
+      phase: 'verify',
+      hop: 4,
+      tool: 'verify_build',
+    });
+    expect(result.success).toBe(true);
+    expect(result.success && result.data).toMatchObject({
+      phase: 'verify',
+      hop: 4,
+      tool: 'verify_build',
+    });
+  });
+
+  it('parses a frame carrying each optional field on its own', () => {
+    expect(BuildProgressFrameSchema.safeParse({ phase: 'data', hop: 0 }).success).toBe(true);
+    expect(BuildProgressFrameSchema.safeParse({ phase: 'data', tool: 'create_seed' }).success).toBe(true);
+  });
+
+  it('is a FLOOR: the panel fields objectui already reads survive the parse', () => {
+    // Regression guard for "tighten it to .strict()". Every key below is read
+    // by `extractBuildProgress` off this same frame today; refusing or
+    // stripping them would break the shipping consumer.
+    const shipping = {
+      phase: 'structure' as const,
+      appLabel: 'CRM',
+      items: [{ type: 'object', name: 'contacts' }],
+      done: 1,
+      total: 4,
+      seq: 12,
+    };
+
+    const result = BuildProgressFrameSchema.safeParse(shipping);
+    expect(result.success).toBe(true);
+    expect(result.success && result.data).toMatchObject(shipping);
+  });
+
+  it('REFUSES an undeclared phase, locating it at `phase`', () => {
+    const result = BuildProgressFrameSchema.safeParse({ phase: 'rebuilding', hop: 1 });
+
+    expect(result.success).toBe(false);
+    if (result.success) throw new Error('unreachable: a frame with an undeclared phase parsed');
+
+    const [issue] = result.error.issues;
+    expect(issue.code).toBe('invalid_value');
+    expect(issue.path).toEqual(['phase']);
+  });
+
+  it('REFUSES a frame with no phase at all', () => {
+    const result = BuildProgressFrameSchema.safeParse({ hop: 2, tool: 'verify_build' });
+    expect(result.success).toBe(false);
+    expect(result.success === false && result.error.issues[0].path).toEqual(['phase']);
+  });
+
+  it('REFUSES a malformed hop and an empty tool name', () => {
+    expect(BuildProgressFrameSchema.safeParse({ phase: 'verify', hop: -1 }).success).toBe(false);
+    expect(BuildProgressFrameSchema.safeParse({ phase: 'verify', hop: 1.5 }).success).toBe(false);
+    expect(BuildProgressFrameSchema.safeParse({ phase: 'verify', tool: '' }).success).toBe(false);
+  });
+});
+
+describe('BuildProgressPhase (type)', () => {
+  it('admits every declared member and is assignable from the array', () => {
+    const everyPhase: BuildProgressPhase[] = [...BUILD_PROGRESS_PHASES];
+    expect(everyPhase).toHaveLength(BUILD_PROGRESS_PHASES.length);
+  });
+});
@@ -0,0 +1,134 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { z } from 'zod';
+import { lazySchema } from '../shared/lazy-schema';
+
+/**
+ * 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.
+ */
+
+/**
+ * The closed phase vocabulary, in emission-lifecycle order.
+ *
+ * Membership was MEASURED against the two ends of the channel, not designed —
+ * every member below is one a real producer emits or a real consumer already
+ * discriminates:
+ *
+ * - `structure`, `data`, `done` — the consumer's own declared union,
+ *   `ChatBuildProgress['phase']` at `packages/plugin-chatbot/src/ChatbotEnhanced.tsx:163`
+ *   in objectui, and the set its reader discriminates at
+ *   `packages/plugin-chatbot/src/mapMessages.ts:744`
+ *   (`d.phase === 'data' || d.phase === 'done' ? d.phase : 'structure'`).
+ *   `structure` doubles as that reader's coercion default.
+ * - `verify` — the post-apply verification window objectui#7388 asks the panel
+ *   to be able to name, and the reason cloud#2172 ruled this vocabulary into
+ *   the spec. Corroborated in this repo by the `verify_build` tool that
+ *   `service-ai-studio` actually registers
+ *   (`../system/constants/platform-tool-names`).
+ *
+ * Order is the order a build turn passes through these states; it is NOT a
+ * scale. ⛔ Consumers compare phases by VALUE — never by index, and never by
+ * assuming every phase occurs (a turn that applies no seed data never reports
+ * `data`, and `apply_edit` turns need not report `structure`).
+ *
+ * Exported as an array as well as a schema so a consumer can build an
+ * exhaustive per-phase label map without forcing the lazy schema to
+ * construct just to read `.options`.
+ */
+export const BUILD_PROGRESS_PHASES = ['structure', 'data', 'verify', 'done'] as const;
+
+/**
+ * The phase a `data-build-progress` frame is reporting.
+ *
+ * Closed on purpose: an unrecognised value is REFUSED here, loudly, at the
+ * seam that can still say which value was wrong. The alternative is what
+ * objectui#7388 measured — a silent coercion to a neighbouring phase, which
+ * costs the user a correct-looking label describing something that already
+ * finished.
+ */
+export const BuildProgressPhaseSchema = lazySchema(() => z.enum(BUILD_PROGRESS_PHASES));
+
+/**
+ * The stream part name this vocabulary rides, as a Vercel UI-message-stream
+ * custom data-part name. Emitters pass it as `ctx.onProgress({ type, id, data })`
+ * and the objectui reader selects parts by exactly this string, so it is the
+ * one literal both ends must agree on.
+ */
+export const BUILD_PROGRESS_FRAME_TYPE = 'data-build-progress';
+
+/**
+ * The `data` payload of a `data-build-progress` frame — a FLOOR, not a
+ * ceiling.
+ *
+ * Declared minimal on purpose, and deliberately **not** strict. The same frame
+ * already carries the objectui build panel's own presentation fields
+ * (`appLabel`, `items`, `done`, `total`, `seq` — read in `extractBuildProgress`),
+ * which are the consumer's to shape; a strict schema here would refuse every
+ * frame shipping today and would claim ownership of fields this package does
+ * not define. What this schema asserts is the part any consumer may rely on:
+ * a frame says which phase it is in, and may say which verification hop it is
+ * on and which tool that hop is running.
+ */
+export const BuildProgressFrameSchema = lazySchema(() => z.looseObject({
+  /** Which phase of the build turn this frame reports. */
+  phase: BuildProgressPhaseSchema.describe('Build-turn phase this frame reports'),
+  /**
+   * Which hop of the post-apply verification loop this frame is on — the
+   * counter behind the "9 tool calls" cloud#1838 measured, so the panel can
+   * show motion through a window that is otherwise a single flat phase.
+   *
+   * Typed as a non-negative integer rather than pinned to a base: whether the
+   * loop counts its first hop as 0 or 1 is part of the emitter's placement,
+   * which cloud#2172 owns and this card does not decide. ⛔ Consumers render it
+   * as progress, never as an index into anything here.
+   */
+  hop: z.number().int().nonnegative().optional().describe('Post-apply verification hop this frame reports'),
+  /**
+   * Name of the tool the current hop is running, e.g. `verify_build`.
+   *
+   * A free string, not a closed set: the runtime's executable tool set is
+   * registered at boot and legitimately includes plugin-contributed names that
+   * `PLATFORM_PROVIDED_TOOL_NAMES` cannot know about
+   * (`../system/constants/platform-tool-names`). Consumers treat it as a label.
+   */
+  tool: z.string().min(1).optional().describe('Name of the tool the current hop is running'),
+}));
+
+/** A phase from the closed {@link BUILD_PROGRESS_PHASES} vocabulary. */
+export type BuildProgressPhase = z.infer<typeof BuildProgressPhaseSchema>;
+
+/** The `data` payload of a `data-build-progress` frame. */
+export type BuildProgressFrame = z.input<typeof BuildProgressFrameSchema>;
@@ -19,6 +19,7 @@
  * - Embedding       — embedding model + vector store references
  * - Usage           — token accounting + per-call cost
  * - MCP             — references and bindings to external MCP servers
+ * - Build Progress  — phase vocabulary for the agent loop's `data-build-progress` frames
  */
 
 export * from './agent.zod';
@@ -35,6 +36,7 @@ export * from './mcp.zod';
 export * from './knowledge-source.zod';
 export * from './knowledge-document.zod';
 export * from './solution-blueprint.zod';
+export * from './build-progress.zod';
 
 // [#12414] entry-nameability: these factories' return types expand to mention
 // `/data`'s `FilterCondition` and `/automation`'s `StateNodeConfig` — both