Skip to content

docs: name both causes of next: null in the state-introspection prose#11275

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hotlong merged 1 commit into from
Aug 23, 2026
+3 −2
Merged

docs: name both causes of next: null in the state-introspection prose #11275

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion content/docs/protocol/objectql/state-machine.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -124,7 +124,7 @@ A `state_machine` rule has no per-transition guard. To gate a transition on a pr
Because the transition table is data, both UIs and Agents can ask "from this state, what's legal next?" instead of parsing a formula.

- **In code**, `legalNextStates(objectSchema, field, currentState)` from `@objectstack/objectql` returns the declared next states, `[]` when the state has no outgoing edges (an explicit `[]` **or** a state the table never mentions — introspection does not distinguish the two, enforcement does), or `null` when no `state_machine` rule governs the field.
- **Over HTTP**, `GET /api/v1/meta/object/:name/state/:field?from=:state` returns `{ object, field, from, next }`, where `next` is the legal-next list (or `null`).
- **Over HTTP**, `GET /api/v1/meta/object/:name/state/:field?from=:state` returns `{ object, field, from, next }`, where `next` is the legal-next list, or `null` for **either** of two reasons: no `state_machine` rule governs the field, **or** `?from=` was omitted (no `from` ⇒ no transition table to answer with). A `null` from a call that passed no `from` is therefore not evidence that the field has no state machine — re-ask with `?from=`.

<Callout type="info">
When an AI Agent or Flow tries to update `status` to `approved` while the record is in `draft`, the write fails with a `ValidationError` (field error code `invalid_transition`) — the AI-mistake protection the rule exists for. There is no automatic injection of per-state AI instructions into the prompt; the guardrail is the enforced transition table.
Expand Down
3 changes: 2 additions & 1 deletion skills/objectstack-automation/SKILL.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -279,7 +279,8 @@ Notes:
transition, e.g. `previous.status != 'escalated' && record.status == 'escalated'`.
- **Introspection:** `GET /api/v1/meta/object/:name/state/:field?from=:state`
returns the legal next states so UIs/agents can read the transition table
instead of hard-coding it (`next: null` when no FSM governs the field).
instead of hard-coding it (`next: null` = no FSM governs the field, **or**
`?from=` was omitted — always pass `from`).
- Predicate conditions in sibling rules evaluate against the merged record in
the **`record.<field>`** CEL scope (bare field names do not resolve).

Expand Down
Loading