Measured while implementing #10178 (canonical spelling of the state-introspection route). Filed unassigned; recording only, not claiming. Not fixed there — #10178 is a spelling correction and this is a semantics correction, so it would have been unreviewable scope creep on a governed-surface PR.
The dispatcher branch computes the answer as, verbatim from the runtime's /meta domain module:
constnext=from===undefined ? null : legalNextStates(schema,field,from);
So next: null has two causes: no state_machine rule governs the field, and the caller omitted ?from=. Both published prose sites name only the first:
content/docs/protocol/objectql/state-machine.mdx — "returns { object, field, from, next }, where next is the legal-next list (or null)" then, in the sibling in-code bullet, attributes null to "no state_machine rule governs the field".skills/objectstack-automation/SKILL.md — "(next: null when no FSM governs the field)".
A reader who calls the route without from therefore gets null and, on the documentation, concludes the object declares no state machine. For the skill that reading is the more expensive one: it is the corpus an AI author works from, and the wrong conclusion is "this object has no lifecycle to respect".
The repo already knows the correct semantics on the QA side — docs/qa/platform-checklist/areas/api-backend.json clause states "?from omitted returns next:null (no from ⇒ no transition table)". So this is prose lagging behind a fact the checklist already asserts, not an open question.
Suggested fix: name both causes at each site. Note the skill is under skills/**, a governed surface, so whichever PR carries site 2 needs draft + human merge + review from os-zhuang.
Related: #10178 (the spelling half of the same two lines).
Measured while implementing #10178 (canonical spelling of the state-introspection route). Filed unassigned; recording only, not claiming. Not fixed there — #10178 is a spelling correction and this is a semantics correction, so it would have been unreviewable scope creep on a governed-surface PR.
The dispatcher branch computes the answer as, verbatim from the runtime's
/metadomain module:So
next: nullhas two causes: nostate_machinerule governs the field, and the caller omitted?from=. Both published prose sites name only the first:content/docs/protocol/objectql/state-machine.mdx— "returns{ object, field, from, next }, wherenextis the legal-next list (ornull)" then, in the sibling in-code bullet, attributesnullto "nostate_machinerule governs the field".skills/objectstack-automation/SKILL.md— "(next: nullwhen no FSM governs the field)".A reader who calls the route without
fromtherefore getsnulland, on the documentation, concludes the object declares no state machine. For the skill that reading is the more expensive one: it is the corpus an AI author works from, and the wrong conclusion is "this object has no lifecycle to respect".The repo already knows the correct semantics on the QA side —
docs/qa/platform-checklist/areas/api-backend.jsonclause states "?from omitted returns next:null (no from ⇒ no transition table)". So this is prose lagging behind a fact the checklist already asserts, not an open question.Suggested fix: name both causes at each site. Note the skill is under
skills/**, a governed surface, so whichever PR carries site 2 needs draft + human merge + review from os-zhuang.Related: #10178 (the spelling half of the same two lines).