Skip to content

Commit 421afed

Browse files
committed
fix(spec): put the build-progress aliases on the ADR-0122 convention and correct the counts a new schema moves
Three gate-named corrections, all mechanical consequences of the new export: - ADR-0122 (`check:spec-parsed-alias`): the bare alias is the AUTHOR state, so `BuildProgressPhase` becomes `z.input`. Both schemas are isomorphic — no default, no transform anywhere in either tree — so neither gets a redundant `XParsed` synonym; they are pinned in `type-alias-convention.pin.test.ts` instead, which is the route the ADR prescribes and the gate reads as its exemption registry. tsc is what proves the two new pins, and the pin count moves 783 -> 785 in all three places that state it. - `check:llms-txt`: the hand-kept inventory ships to AI consumers inside the tarball; `ai` 11 -> 12 and the total 200 -> 201, with the domain's subject list naming the new module rather than only its count. - `check:quick-reference-counts`: the AI section was complete at 11 of 11, so it stays complete at 12 of 12 with a row for the new reference page. Claude-Session: https://claude.ai/code/session_01KB5PFtxuy1x3dcR5gxudx6 Co-authored-by: Claude <noreply@anthropic.com>
1 parent fbae68b commit 421afed

4 files changed

Lines changed: 33 additions & 7 deletions

File tree

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,7 @@ Runtime environment, logging, jobs, caching, and observability.
108108
| **[Translation](/docs/references/system/translation)** | `translation.zod.ts` | Translation | i18n support |
109109
| **[Worker](/docs/references/system/worker)** | `worker.zod.ts` | Worker | Background workers |
110110

111-
## AI Protocol (11 of 11 schemas)
111+
## AI Protocol (12 of 12 schemas)
112112

113113
AI/ML capabilities - agents, skills, tools, MCP exposure, RAG, and cost tracking.
114114

@@ -125,6 +125,7 @@ AI/ML capabilities - agents, skills, tools, MCP exposure, RAG, and cost tracking
125125
| **[Knowledge Document](/docs/references/ai/knowledge-document)** | `knowledge-document.zod.ts` | KnowledgeDocument, KnowledgeChunk | RAG documents and chunks |
126126
| **[Usage](/docs/references/ai/usage)** | `usage.zod.ts` | AIUsageRecord, TokenUsage | AI usage and cost tracking |
127127
| **[Solution Blueprint](/docs/references/ai/solution-blueprint)** | `solution-blueprint.zod.ts` | BlueprintObject, BlueprintApp | Blueprint format for AI app generation |
128+
| **[Build Progress](/docs/references/ai/build-progress)** | `build-progress.zod.ts` | BuildProgressPhase, BuildProgressFrame | Phases the agent loop streams while building and verifying |
128129

129130
## API Protocol (17 of 31 schemas)
130131

‎packages/spec/llms.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ const query = {
7777

7878
---
7979

80-
## 3. Schema Inventory by Domain (200 schemas)
80+
## 3. Schema Inventory by Domain (201 schemas)
8181

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

‎packages/spec/src/ai/build-progress.zod.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,7 @@ export const BuildProgressFrameSchema = lazySchema(() => z.looseObject({
128128
}));
129129

130130
/** A phase from the closed {@link BUILD_PROGRESS_PHASES} vocabulary. */
131-
export type BuildProgressPhase = z.infer<typeof BuildProgressPhaseSchema>;
131+
export type BuildProgressPhase = z.input<typeof BuildProgressPhaseSchema>;
132132

133133
/** The `data` payload of a `data-build-progress` frame. */
134134
export type BuildProgressFrame = z.input<typeof BuildProgressFrameSchema>;

‎packages/spec/src/type-alias-convention.pin.test.ts‎

Lines changed: 28 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -271,9 +271,11 @@ import type * as M185 from './shared/epoch.zod.js';
271271
// [#18122] The closed duration vocabulary beside that instant — new module,
272272
// next free index (M186 is `automation/schedule-organization.zod.ts`).
273273
import type * as M187 from './shared/duration.zod.js';
274+
// [#18451] The build-progress PHASE vocabulary -- new module, next free index.
275+
import type * as M188 from './ai/build-progress.zod.js';
274276

275277
// ---------------------------------------------------------------------------
276-
// 783 isomorphic aliases: `z.input` === `z.infer`, so no `XParsed` is declared.
278+
// 785 isomorphic aliases: `z.input` === `z.infer`, so no `XParsed` is declared.
277279
//
278280
// That number is machine-checked, not hand-kept. The runtime companion at the
279281
// bottom of this file recomputes the pin count from the source and asserts that
@@ -1026,6 +1028,18 @@ export type Iso868 = Assert<Eq< z.input< typeof M185.EpochMs >, z.infer< typeof
10261028
export type Iso873 = Assert<Eq< z.input< typeof M187.DurationMs >, z.infer< typeof M187.DurationMs > >>;
10271029
export type Iso874 = Assert<Eq< z.input< typeof M187.DurationSeconds >, z.infer< typeof M187.DurationSeconds > >>;
10281030

1031+
// ai/build-progress.zod.ts -- the closed build-progress PHASE vocabulary
1032+
// (#18451, cloud#2172 ruling A) and the frame that carries it. The enum has
1033+
// no default and no transform; the frame is a `z.looseObject` whose three
1034+
// members are a bare enum and two plain optionals, so both are the (RISE)
1035+
// case. The frame pin is the load-bearing one: it is deliberately a FLOOR
1036+
// that passes the consumer's own panel fields through untouched, and the day
1037+
// someone gives `phase` or `hop` a `.default()` to 'help' a producer that
1038+
// omits it, author state and parsed state part company -- this is the line
1039+
// that says so by name.
1040+
export type Iso875 = Assert<Eq< z.input< typeof M188.BuildProgressPhaseSchema >, z.infer< typeof M188.BuildProgressPhaseSchema > >>;
1041+
export type Iso876 = Assert<Eq< z.input< typeof M188.BuildProgressFrameSchema >, z.infer< typeof M188.BuildProgressFrameSchema > >>;
1042+
10291043
// shared/value-domain.zod.ts — the ONE standard-domain vocabulary (#14168);
10301044
// `SpecifierValueDomainSchema` (Iso758) is an alias of it, so both pins hold
10311045
// or fall together. A `z.enum` has no default or transform, the (RISE) case.
@@ -1664,7 +1678,7 @@ describe('ADR-0122 type-alias convention', () => {
16641678
// this title and the section header above the pin list — are now asserted
16651679
// against the recomputed count below, so neither can go stale without a red
16661680
// test naming it.
1667-
it('still declares all 783 isomorphic pins', () => {
1681+
it('still declares all 785 isomorphic pins', () => {
16681682
// The truth of each pin is proved by tsc, not here — an `Assert<Eq<...>>`
16691683
// that stops holding is a compile error with the alias named. What tsc
16701684
// cannot notice is a pin that was DELETED: removing the assertion removes
@@ -2227,7 +2241,18 @@ describe('ADR-0122 type-alias convention', () => {
22272241
// `startTime: durationMs`-style `.default()` or a `.transform()` that
22282242
// fills one member from another, this pin is the line that says the alias
22292243
// has gained a second shape.
2230-
expect(pins).toHaveLength(783);
2244+
// 783 -> 785 is #18451's build-progress PHASE vocabulary
2245+
// (ai/build-progress.zod.ts, new module slot M188): `BuildProgressPhase`
2246+
// and `BuildProgressFrame`, the (RISE) case twice. The enum is a bare
2247+
// `z.enum` like the `ConnectorActionEffectSchema` pin that first taught
2248+
// this count to rise; the frame is a `z.looseObject` of one enum and two
2249+
// plain optionals. Neither carries a default or a transform, so no
2250+
// `XParsed` is declared and both come here instead. +2 added.
2251+
//
2252+
// Note the number is the same 783 -> 785 the DURATION block above records,
2253+
// arrived at from the same 783 after #16059's retirement took it back down.
2254+
// The two entries are different movements that share a pair of endpoints.
2255+
expect(pins).toHaveLength(785);
22312256

22322257
// The count is stated in PROSE twice as well — this case's title and the
22332258
// section header above the pin list — and until #6605 nothing read either

0 commit comments

Comments
 (0)