feat(spec): a blueprint formula field can state its expression - #4577
Merged
Conversation
`BlueprintFieldSchema.type` is the FULL `FieldType` enum, so the AI-build design step could always NAME a `formula` field — but neither the lenient schema nor the OpenAI-strict mirror the model generates against had any key for the body. There was no way, anywhere on that surface, to say what the formula computed. It materialized bare, and cloud graph-lint then correctly reported `formula_without_expression` with the fix "Set field expression to a CEL formula" — which the agent could not write in the blueprint it was holding. Detected, but unfixable on the surface that produced it. This is the same hole `summaryOperations` closed for roll-ups in cloud#970; `formula` was left behind. It bites hardest through `nameField`, whose own guidance tells the model to use a formula for numbered entities (invoice / ticket) composing "number · name" — following that advice produced a record title blank on every card, lookup chip and breadcrumb. The PIN matters more than the key. The root cause is not a forgotten property: two schemas describe the same shape and nothing forced them to agree. The mirror is what the model may EMIT, the lenient schema is what downstream READS, and drift either way silently drops authored config. A new test asserts the two field schemas carry exactly the same keys, so the next key added to one cannot go missing from the other. `authorable-surface.json` records exactly one new key (`ai/BlueprintField:expression`). The API surface is unchanged — a Zod field adds no exports. Verification: blueprint tests 29/29; full suite 132/132; check:api-surface unchanged; check:authorable-surface green after gen:schema. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WnqGjQFQMqd5k81LYV8SCY
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
os-zhuang
marked this pull request as ready for review
August 2, 2026 08:33
os-zhuang
enabled auto-merge
August 2, 2026 08:33
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 107 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
…n` key `content/docs/references/ai/solution-blueprint.mdx` is generated from the schema and enumerates BlueprintField's keys in a table, so adding `expression` makes it stale. Regenerated with `gen:docs`; the diff is exactly the one new row. `check:docs` reports 259 generated files in sync. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WnqGjQFQMqd5k81LYV8SCY
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The framework half of ADR-0078 Phase 2 (#4544, A1 — the authoring path that drops correctly-authored config). Companion change in the
cloudrepo carries the value through to materialization.A type it could name but never complete
BlueprintFieldSchema.typeis the fullFieldTypeenum, so the AI-build design step could always author{ type: 'formula' }. But neither the lenient schema nor the OpenAI-strict mirror the model actually generates against had any key for the body.There was no way, anywhere on that surface, to say what the formula computed.
So it materialized bare — and cloud's graph-lint then correctly reported
formula_without_expressionwith the fix "Set field expression to a CEL formula", which the agent could not write in the blueprint it was holding. Detected, but unfixable on the surface that produced it. The only escape was to abandon the blueprint path for granularapply_editcalls.The same hole, one field type over
This is exactly what
summaryOperationsclosed for roll-ups in cloud#970. From this file's own test:formulawas simply left behind.It bites hardest through
nameField, whose own guidance tells the model to point at a formula for numbered entities:Following that advice produced a record title that is blank on every card, lookup chip and breadcrumb (ADR-0079).
The pin matters more than the key
A1's root cause is not a forgotten property. It is that two schemas describe the same shape and nothing forced them to agree:
Drift in either direction silently drops authored config. That asymmetry is how
formulagot left behind whensummaryOperationswas added.A new test asserts the two field schemas carry exactly the same keys, so the next key added to one cannot go missing from the other.
Verification
expressionpresence in both schemas, and a formula round-trip through the lenient schema)check:api-surfaceunchanged without regeneration — a Zod field adds no exportscheck:authorable-surfaceflagged exactly one new key,ai/BlueprintField:expression, recorded viagen:schemaGenerated by Claude Code