Skip to content

Commit 400e8cc

Browse files
committed
fix(spec): objectName is planned — the liveness row warns its authors and the describe says no door reads it yet
Drills flow.variables in the liveness ledger (the five wired keys live, objectName planned with authorWarn), drops the undrilled-container row, words the describe, TSDoc, docs and changeset in the planned style, pins the author warning, and gives flow-input-unknown-object an os explain entry. Claude-Session: https://claude.ai/code/session_01JQwxbaiSvS6eyjEknCGKao Co-authored-by: Claude <noreply@anthropic.com>
1 parent f06ad23 commit 400e8cc

8 files changed

Lines changed: 141 additions & 20 deletions

File tree

‎.changeset/29442-flow-start-input-record.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,9 @@ feat(spec): a flow start input can declare that it is the id of a record of a na
99
Clause-②: yes (widening)
1010
Metadata-protocol: added
1111

12-
`FlowVariableSchema` declares one optional key, `objectName`: on an input (`isInput: true`), it says the input's value is the id of one record of the named object, e.g. `{ name: 'accountId', type: 'text', isInput: true, objectName: 'crm_account' }`. The rule it states: every door that starts the flow by name (the trigger route, an action of type flow over REST and MCP `run_action`, a declared endpoint of type flow) loads a declared input from that object in the caller's own scope before the run exists; an id the caller cannot read there is refused `404 RECORD_NOT_FOUND`, and a value that is not an id is refused `400 VALIDATION_FAILED` naming the input. An input without the declaration keeps the visible-read rule: it is judged as a record only where the flow's own definition reads it as a record id.
12+
`FlowVariableSchema` declares one optional key, `objectName`: on an input (`isInput: true`), it says the input's value is the id of one record of the named object, e.g. `{ name: 'accountId', type: 'text', isInput: true, objectName: 'crm_account' }`. The key is **planned**: no door reads it yet, and `os validate` warns on every flow that writes it (`liveness-planned-property`). The contract it states, for the start doors to enforce: every door that starts the flow by name (the trigger route, an action of type flow over REST and MCP `run_action`, a declared endpoint of type flow) loads a declared input from that object in the caller's own scope before the run exists; an id the caller cannot read there is refused `404 RECORD_NOT_FOUND`, and a value that is not an id is refused `400 VALIDATION_FAILED` naming the input. An input without the declaration keeps the visible-read rule: it is judged as a record only where the flow's own definition reads it as a record id.
1313

1414
- **Spec.** `objectName` is an object name (snake_case) and is refused on a variable that is not an input, since no caller's value reaches one. `type` stays the data type: the variable holds the id. A `reference` or `object` key on a flow variable is still refused, and the refusal now names `objectName`. The flow form's variables repeater gains the column, labelled in the metadata-form bundles (en, zh-CN, ja-JP, es-ES).
1515
- **Lint.** `flow-input-unknown-object`: a declared object the stack does not define is a warning (it may come from another installed package), and an error at the runtime publish gate when the write's package closure does not reach it, the verdict `flow-trigger-unknown-object` gives a trigger object. A `sys_` name is not judged.
1616

17-
This is the contract half: the start doors read the declaration in a later change, and until then no door loads a declared input. Nothing to do for existing flows.
17+
This is the contract half: the start doors read the declaration in a later change, and until then no door loads a declared input, so a start that hands the input an id the caller cannot read still runs. Nothing to do for existing flows.

‎content/docs/automation/flows.mdx‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2029,7 +2029,7 @@ variables: [
20292029
| `isInput` | `boolean` | Available as input parameter |
20302030
| `isOutput` | `boolean` | Available as output parameter |
20312031
| `defaultValue` | `unknown` | Bound at run start when no parameter supplies one — this is what makes the declaration a guarantee. Optional |
2032-
| `objectName` | `string` | On an input only: the input is the id of a record of this object. See [a start input that is a record id](#a-start-input-that-is-a-record-id). Optional |
2032+
| `objectName` | `string` | **Planned.** On an input only (refused at parse on any other variable): the input is the id of a record of this object. No start door reads it yet. See [a start input that is a record id](#a-start-input-that-is-a-record-id). Optional |
20332033

20342034
### `defaultValue` — declaring a variable is not the same as binding it
20352035

@@ -2123,8 +2123,17 @@ export const CloseAccount = defineFlow({
21232123
});
21242124
```
21252125

2126-
The rule: every door that starts the flow by name (the trigger route, an action
2127-
of `type: 'flow'` over REST and MCP `run_action`, a declared endpoint of
2126+
<Callout type="warn">
2127+
**Planned — no door applies this yet.** The declaration parses, is refused on a
2128+
variable that is not an input, and is linted, but no start door loads a
2129+
declared input today: a start that hands it an id the caller cannot read still
2130+
runs. `os validate` warns on every flow that writes it
2131+
(`liveness-planned-property`). The contract below is what the start doors will
2132+
enforce.
2133+
</Callout>
2134+
2135+
The contract: every door that starts the flow by name (the trigger route, an
2136+
action of `type: 'flow'` over REST and MCP `run_action`, a declared endpoint of
21282137
`type: 'flow'`) loads a declared input from the named object in the caller's
21292138
own scope before the run exists. An id the caller cannot read there is refused
21302139
`404` `RECORD_NOT_FOUND`; a value that is not an id is refused `400`

‎packages/lint/src/lint-liveness-properties.test.ts‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,35 @@ describe('lintLivenessProperties', () => {
158158
expect(ruleOf(findings, 'nodes.outputSchema')).toBeUndefined();
159159
});
160160

161+
// #29442 — `flow.variables[].objectName` is declared before any start door
162+
// reads it, so its row is `planned` + `authorWarn`. Pinned through the SHIPPED
163+
// ledger and an array of variables, so the drill (`variables.objectName`)
164+
// and the array fan-out both have to hold for the author to be told.
165+
it('warns on a flow input declared a record reference — planned, nothing reads it yet', () => {
166+
const findings = lintLivenessProperties({
167+
flows: [{
168+
name: 'close_account',
169+
variables: [
170+
{ name: 'note', type: 'text', isInput: true },
171+
{ name: 'accountId', type: 'text', isInput: true, objectName: 'crm_account' },
172+
],
173+
nodes: [{ id: 'start', type: 'start' }],
174+
}],
175+
});
176+
const warned = findings.filter((f) => f.message.includes('sets `variables.objectName`'));
177+
expect(warned).toHaveLength(1);
178+
expect(warned[0].rule).toBe('liveness-planned-property');
179+
expect(warned[0].hint).toContain('nothing reads it yet');
180+
// The live siblings the drill graded stay silent.
181+
for (const key of ['name', 'type', 'isInput', 'isOutput', 'defaultValue']) {
182+
expect(ruleOf(findings, `variables.${key}`), key).toBeUndefined();
183+
}
184+
// And a flow that writes no `objectName` draws nothing about it.
185+
expect(lintLivenessProperties({
186+
flows: [{ name: 'f2', variables: [{ name: 'note', type: 'text', isInput: true }], nodes: [] }],
187+
}).filter((f) => f.message.includes('objectName'))).toEqual([]);
188+
});
189+
161190
it('warns on an experimental prop with no authorWarn of its own (tool.outputSchema)', () => {
162191
// `experimental` warns implicitly — shouldWarn() treats a declared-but-
163192
// unenforced guarantee like an opted-in dead prop. Repointed from

‎packages/lint/src/rule-explanations.ts‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2072,6 +2072,33 @@ const FLOW_TRIGGER_UNKNOWN_OBJECT_EXPLANATION: RuleExplanation = {
20722072
],
20732073
};
20742074

2075+
// `flow-input-unknown-object` (#29442) shares the rule file, the hedge and the
2076+
// closure split with `flow-trigger-unknown-object` above; what differs is the
2077+
// position it reads and what a wrong name costs.
2078+
2079+
const FLOW_INPUT_UNKNOWN_OBJECT_EXPLANATION: RuleExplanation = {
2080+
rule: 'flow-input-unknown-object',
2081+
covers: 'why an unknown start-input object warns, and when it refuses',
2082+
paragraphs: [
2083+
'A flow input may declare that its value is the id of a record of a named object, with `objectName` on ' +
2084+
'the variable. The start doors are to load such an input from exactly that name in the caller\'s own ' +
2085+
'scope before the run exists, so a name no object answers to would refuse every start that supplies ' +
2086+
'the input. Names match exactly — `app_candidate`, not `candidate`. The declaration is planned: no ' +
2087+
'door reads it yet, and the property lint says so separately.',
2088+
'The rule asks whether this stack defines the object. One it does not define may be declared by ' +
2089+
'another installed package, which a build of this stack cannot see, so the finding is a warning and ' +
2090+
'can be ignored when such a package declares the object; a `sys_` name is a platform object and is ' +
2091+
'not judged. A start that omits the input is not affected, so this is not a verdict that the flow ' +
2092+
'never runs.',
2093+
'A write into a package is judged against that package\'s closure instead: its own objects, the objects ' +
2094+
'of the packages its manifest declares in `dependencies`, and platform objects. An object outside it ' +
2095+
'is one the package never declared it may reference, so there the finding is an error and the publish ' +
2096+
'is refused, the verdict `flow-trigger-unknown-object` gives a trigger object. Declare a dependency on ' +
2097+
'the package that defines the object, or name an object inside the closure. A `sys_` name is not ' +
2098+
'judged there either.',
2099+
],
2100+
};
2101+
20752102
// ── Validation rules that compile at publish time ───────────────────────────
20762103
// `validate-rule-compilability.ts` and `validate-rule-schema-formats.ts`: the
20772104
// write path's fail-open skip and the runtime's ajv environment are shared,
@@ -5563,6 +5590,7 @@ export const RULE_EXPLANATIONS: Readonly<Record<string, RuleExplanation>> = Obje
55635590
[FLOW_TRIGGER_UNKNOWN_EVENT_EXPLANATION.rule]: FLOW_TRIGGER_UNKNOWN_EVENT_EXPLANATION,
55645591
[FLOW_API_TRIGGER_SECRET_MISSING_EXPLANATION.rule]: FLOW_API_TRIGGER_SECRET_MISSING_EXPLANATION,
55655592
[FLOW_TRIGGER_UNKNOWN_OBJECT_EXPLANATION.rule]: FLOW_TRIGGER_UNKNOWN_OBJECT_EXPLANATION,
5593+
[FLOW_INPUT_UNKNOWN_OBJECT_EXPLANATION.rule]: FLOW_INPUT_UNKNOWN_OBJECT_EXPLANATION,
55665594
[VALIDATION_RULE_REGEX_UNCOMPILABLE_EXPLANATION.rule]: VALIDATION_RULE_REGEX_UNCOMPILABLE_EXPLANATION,
55675595
[VALIDATION_RULE_JSON_SCHEMA_UNCOMPILABLE_EXPLANATION.rule]: VALIDATION_RULE_JSON_SCHEMA_UNCOMPILABLE_EXPLANATION,
55685596
[VALIDATION_RULE_JSON_SCHEMA_UNKNOWN_FORMAT_EXPLANATION.rule]: VALIDATION_RULE_JSON_SCHEMA_UNKNOWN_FORMAT_EXPLANATION,

‎packages/lint/src/validate-flow-trigger-readiness.test.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -182,6 +182,17 @@ describe('validateFlowTriggerReadiness', () => {
182182
expect(findings[0].message).toContain("declares input 'invoiceId' a record of object 'billing_invoice'");
183183
expect(findings[0].hint).toContain("set the input's objectName to an object inside that closure");
184184
});
185+
186+
it('routes the hedge and the closure split to `os explain`, keeping the fix one line', () => {
187+
expect(explanationOf(FLOW_INPUT_UNKNOWN_OBJECT)).toMatch(/another installed package/);
188+
expect(explanationOf(FLOW_INPUT_UNKNOWN_OBJECT)).toMatch(/closure/);
189+
const [finding] = validateFlowTriggerReadiness({
190+
objects: [candidateObject],
191+
flows: [inputFlow([{ name: 'invoiceId', type: 'text', isInput: true, objectName: 'billing_invoice' }])],
192+
});
193+
expect(finding.hint).not.toContain('\n');
194+
expect(finding.hint.length).toBeLessThanOrEqual(200);
195+
});
185196
});
186197

187198
it('warns when an auto-triggered flow has no explicit status (defaults to draft)', () => {

‎packages/spec/liveness/flow.json‎

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,43 @@
6262
"variables": {
6363
"status": "live",
6464
"evidence": "packages/services/service-automation/src/engine.ts",
65-
"note": "{name,isInput,isOutput} wired. `objectName` (#29425 ruling A, declared by #29442): an input's declaration that its value is the id of a record of the named object. PLANNED consumer, not yet wired: the start doors in packages/runtime/src/flow-start-admission.ts load a declared input from that object in the caller's scope before the run exists — the server half, Blocked-by #29442. Until it lands the key is parsed, validated (input-only, an object name) and linted (flow-input-unknown-object), and no door reads it. `variables` is an undrilled container (scripts/liveness/undrilled-containers.baseline.json), so the key has no row of its own and this note is its record."
65+
"note": "{name,type,isInput,isOutput,defaultValue} wired; drilled per key (#29442) so `objectName` can carry its own `planned` row and author warning — the blanket row could not say that one child is not read yet.",
66+
"children": {
67+
"name": {
68+
"status": "live",
69+
"verifiedAt": "2026-11-02",
70+
"evidence": "packages/services/service-automation/src/dag-traversal.ts#seedDeclaredVariables (binds each declared variable under `v.name`, from `context.params[v.name]` or its default)"
71+
},
72+
"type": {
73+
"status": "live",
74+
"verifiedAt": "2026-11-02",
75+
"evidence": "ui/apps/console/src/pages/developer/FlowRunsPage.tsx#FlowTestRunner (the Flow Runs test runner picks each input's widget and coerces its value by `v.type`)",
76+
"note": "An open string: no engine path coerces by it; the Console test runner is its reader."
77+
},
78+
"isInput": {
79+
"status": "live",
80+
"verifiedAt": "2026-11-02",
81+
"evidence": "packages/services/service-automation/src/dag-traversal.ts#seedDeclaredVariables (only an `isInput` variable is bound from the caller's params)"
82+
},
83+
"isOutput": {
84+
"status": "live",
85+
"verifiedAt": "2026-11-02",
86+
"evidence": "packages/services/service-automation/src/dag-traversal.ts#executeWithoutRetry (an `isOutput` variable's final value is copied onto the run result's output)"
87+
},
88+
"defaultValue": {
89+
"status": "live",
90+
"verifiedAt": "2026-11-02",
91+
"evidence": "packages/services/service-automation/src/dag-traversal.ts#seedDeclaredVariables (bound when no param supplies the name, #4697)"
92+
},
93+
"objectName": {
94+
"status": "planned",
95+
"verifiedAt": "2026-11-02",
96+
"evidence": "packages/spec/src/automation/flow.zod.ts#FlowVariableSchema (the superRefine that refuses `objectName` on a variable that is not an input — the one place the key is read today)",
97+
"authorWarn": true,
98+
"authorHint": "Keep it, but nothing reads it yet: no start door loads a declared input from its object until the server half of #29425 ruling A ships, so an id the caller cannot read still starts a run.",
99+
"note": "PLANNED RECORD (#29442, the spec half of #29425 ruling A 6580257050): an input's declaration that its value is the id of one record of the named object. Parsed, refused on a non-input (the evidence above) and linted (`flow-input-unknown-object` in packages/lint/src/validate-flow-trigger-readiness.ts). No door reads it: the start doors' third question (packages/runtime/src/flow-start-admission.ts, `flowDeclaredRecordReads` / `refuseUnreadableFlowStartRecords` in action-execution.ts) judges only inputs the definition reads in plain sight. Carrier: the #29425 server half, Blocked-by #29442 (every start door loads a declared input in the caller's scope, 404 RECORD_NOT_FOUND / 400 VALIDATION_FAILED). Flip to `live` on the commit that cites that reader, drop `authorWarn` / `authorHint` and the describe's planned sentence in that same edit."
100+
}
101+
}
66102
},
67103
"edges": {
68104
"status": "live",

‎packages/spec/scripts/liveness/undrilled-containers.baseline.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,6 @@
9393
"flow/nodes.inputSchema",
9494
"flow/nodes.position",
9595
"flow/nodes.waitEventConfig",
96-
"flow/variables",
9796
"hook/retryPolicy",
9897
"job/retryPolicy",
9998
"manifest/contributes.kinds",

‎packages/spec/src/automation/flow.zod.ts‎

Lines changed: 22 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -232,16 +232,24 @@ export const FLOW_PAUSE_CAPABLE_NODE_TYPES: readonly string[] = [
232232
*
233233
* ## `objectName` — a start input that is a record id (#29425 ruling A)
234234
*
235-
* An input may declare that its value is the id of a record of a named
236-
* object. The declaration is what lets every door that starts the flow by
237-
* name judge the input as a record, whether or not the definition reads it as
238-
* one in plain sight: the door loads it from the named object in the caller's
239-
* own scope before the run exists, refusing an unreadable id
235+
* [planned] An input may declare that its value is the id of a record of a
236+
* named object. The contract the declaration states: every door that starts
237+
* the flow by name judges the input as a record, whether or not the definition
238+
* reads it as one in plain sight — the door loads it from the named object in
239+
* the caller's own scope before the run exists, refusing an unreadable id
240240
* `404 RECORD_NOT_FOUND` and a value that is not an id
241241
* `400 VALIDATION_FAILED` naming the input. An input without the declaration
242242
* keeps the visible-read rule (`flowDeclaredRecordReads` in
243243
* `packages/runtime/src/flow-start-admission.ts`).
244244
*
245+
* ⛔ No door applies it yet. This is the spec half; the start doors read the
246+
* declaration in the ruling's server half (Blocked-by #29442). Until then the
247+
* key is parsed, refused on a non-input (below) and linted
248+
* (`flow-input-unknown-object`), and its liveness row is `planned` with an
249+
* author warning (`packages/spec/liveness/flow.json` › `variables.objectName`),
250+
* so an author who writes it is told. Flip the row, drop the warning and the
251+
* describe's planned sentence in the commit that lands the reader.
252+
*
245253
* The spelling is `objectName`, the word the CRUD nodes already use for the
246254
* object they read, and ⛔ not a `type: 'record'` beside it: `type` already
247255
* carries `'record'` in the shipped corpus for a variable that holds a WHOLE
@@ -290,14 +298,15 @@ export const FlowVariableSchema = lazySchema(() => strictObject(
290298
.meta({ title: 'Default Value' }),
291299
objectName: z.string().regex(/^[a-z_][a-z0-9_]*$/).optional()
292300
.describe(
293-
'Declares this input a record reference: its value is the id of one record of the named object ' +
294-
'(the object\'s snake_case name, e.g. `crm_account`). Only on an input (`isInput: true`). Every door ' +
295-
'that starts the flow by name (the trigger route, an action of type flow over REST and MCP run_action, ' +
296-
'a declared endpoint of type flow) loads a declared input from this object in the caller\'s own scope ' +
297-
'before the run exists: an id the caller cannot read there is refused 404 RECORD_NOT_FOUND, and a value ' +
298-
'that is not an id is refused 400 VALIDATION_FAILED naming the input. An input without this declaration ' +
299-
'is judged as a record only where the flow\'s own definition reads it as a record id. `type` stays the ' +
300-
'data type: the variable holds the id the caller sent.',
301+
'[planned] Declares this input a record reference: its value is the id of one record of the named object ' +
302+
'(the object\'s snake_case name, e.g. `crm_account`). Only on an input (`isInput: true`). The contract: ' +
303+
'every door that starts the flow by name (the trigger route, an action of type flow over REST and MCP ' +
304+
'run_action, a declared endpoint of type flow) loads a declared input from this object in the caller\'s ' +
305+
'own scope before the run exists; an id the caller cannot read there is refused 404 RECORD_NOT_FOUND, and ' +
306+
'a value that is not an id is refused 400 VALIDATION_FAILED naming the input. No door applies it yet: ' +
307+
'today the key is parsed and checked, and a start with an id the caller cannot read still runs. An input ' +
308+
'without this declaration is judged as a record only where the flow\'s own definition reads it as a ' +
309+
'record id. `type` stays the data type: the variable holds the id the caller sent.',
301310
)
302311
.meta({ title: 'Record Object' }),
303312
}).superRefine((variable, ctx) => {

0 commit comments

Comments
 (0)