name	typeql-preflight
description	Pre-flight checklist for TypeDB 3 schema edits in the typedb_tactics package. Invoke before writing or editing any .tql schema file to catch known error patterns before running Docker tests.
user-invocable	false

Before editing or writing a TypeQL schema file, run through this checklist and flag any violations:

No rule blocks — TypeDB 3 removed rules. Use fun with with fun name($arg: Type) -> ReturnType: syntax. Violation: [TSV7]
Relation variable syntax — use $r isa T, links (role: $x) — NOT $r (role: $x) isa T. The latter triggers [REP1] even inside fun match bodies.
No dual Object+ThingType declaration — in a single INSERT block, you cannot create a named relation variable $r and also use it as a role player in the same block. Make intermediate relations anonymous. Violation: [REP1]
No variable reuse across pipeline stages for different types — if $e was bound as propositional_expression in stage 1, do not reuse $e for not_expression in stage 2. Use unique names per stage. Violation: [INF11]
Return syntax — return max($m); and return min($m); require parentheses. return max $m; is invalid.
Boolean returns — return true; is invalid. Use let $r = true; return first $r;
-> boolean not -> bool — use -> boolean in function signatures. bool causes [INF2].

Cross-OR-branch function call results — cannot bind a function-call result directly to a variable that appears across OR branches. Use double-let: let $tmp = func(...); let $out = $tmp;. Violation: [CEX18]
OR branch isa type guards — only include isa branches for types that actually play the role being matched in that fun. If a type cannot play the role, TypeDB raises [FIN0]/[QUA1] at schema commit.
No mutual recursion between fun bodies — the function call graph must be a DAG. Violation: [FUN9]
links can be hoisted before { } or { } blocks — valid and faster. isa constraints before the outer OR block cause a parse error — keep those inside branches.

OR branch ordering — for return first functions, put the branch matching the MOST inputs first. For batch/all-rules queries this is the dominant performance lever (confirmed −37% gain in this codebase).
OR branch ordering does NOT help return min/return max — TypeDB evaluates all branches for aggregators; early-exit does not apply.
Keep OR branches inline — do not split into separate functions for dispatch. Cross-function overhead is 147× in TypeDB 3 (confirmed).
One match stage — the optimizer only reorders within a single stage. Splitting into two stages disables cross-constraint optimization.

Check src/typedb_tactics/agent-docs/schema-guide.md for module intent before adding new types.
Run tests in Docker: scripts/run-tests-docker.sh
If adding a new fun, ensure every OR branch has at least one test case that hits it.
Use text2typeql examples as a reference: python3 scripts/find-text2typeql-examples.py "query intent" --top-k 5

name	typeql-preflight
description	Pre-flight checklist for TypeDB 3 schema edits in the typedb_tactics package. Invoke before writing or editing any .tql schema file to catch known error patterns before running Docker tests.
user-invocable	false

Before editing or writing a TypeQL schema file, run through this checklist and flag any violations:

No rule blocks — TypeDB 3 removed rules. Use fun with with fun name($arg: Type) -> ReturnType: syntax. Violation: [TSV7]
Relation variable syntax — use $r isa T, links (role: $x) — NOT $r (role: $x) isa T. The latter triggers [REP1] even inside fun match bodies.
No dual Object+ThingType declaration — in a single INSERT block, you cannot create a named relation variable $r and also use it as a role player in the same block. Make intermediate relations anonymous. Violation: [REP1]
No variable reuse across pipeline stages for different types — if $e was bound as propositional_expression in stage 1, do not reuse $e for not_expression in stage 2. Use unique names per stage. Violation: [INF11]
Return syntax — return max($m); and return min($m); require parentheses. return max $m; is invalid.
Boolean returns — return true; is invalid. Use let $r = true; return first $r;
-> boolean not -> bool — use -> boolean in function signatures. bool causes [INF2].

Cross-OR-branch function call results — cannot bind a function-call result directly to a variable that appears across OR branches. Use double-let: let $tmp = func(...); let $out = $tmp;. Violation: [CEX18]
OR branch isa type guards — only include isa branches for types that actually play the role being matched in that fun. If a type cannot play the role, TypeDB raises [FIN0]/[QUA1] at schema commit.
No mutual recursion between fun bodies — the function call graph must be a DAG. Violation: [FUN9]
links can be hoisted before { } or { } blocks — valid and faster. isa constraints before the outer OR block cause a parse error — keep those inside branches.

OR branch ordering — for return first functions, put the branch matching the MOST inputs first. For batch/all-rules queries this is the dominant performance lever (confirmed −37% gain in this codebase).
OR branch ordering does NOT help return min/return max — TypeDB evaluates all branches for aggregators; early-exit does not apply.
Keep OR branches inline — do not split into separate functions for dispatch. Cross-function overhead is 147× in TypeDB 3 (confirmed).
One match stage — the optimizer only reorders within a single stage. Splitting into two stages disables cross-constraint optimization.

Check src/typedb_tactics/agent-docs/schema-guide.md for module intent before adding new types.
Run tests in Docker: scripts/run-tests-docker.sh
If adding a new fun, ensure every OR branch has at least one test case that hits it.
Use text2typeql examples as a reference: python3 scripts/find-text2typeql-examples.py "query intent" --top-k 5

typeql-preflight

Mais deste repositório