Locy Errors and Limits¶
Common Error Classes¶
- Parse errors: invalid Locy syntax.
- Compile errors: invalid dependencies, type/schema mismatches, stratification violations.
- Runtime errors: timeout, iteration limit, memory constraints, mutation constraints, cancellation.
A program refused for cost gets a dedicated error, never the generic query error a broken program raises, so a caller can tell "too expensive" from "wrong" without reading the message:
| Refusal | Rust | Python |
|---|---|---|
Timeout (the evaluation's timeout, or the database query_timeout when unset) |
UniError::Timeout { timeout_ms } |
UniTimeoutError |
Memory pool (max_memory) or a relation over max_derived_bytes |
UniError::MemoryLimitExceeded { limit_bytes, message } |
UniMemoryLimitExceededError |
| Stopped at a stratum / iteration boundary | UniError::LocyIncomplete |
UniLocyIncompleteError |
Cypher raises the same variants for the same conditions.
Cancelling the token attached to an evaluation aborts it with UniError::Cancelled (UniCancelledError in Python). Enforcement races the whole evaluation, so a long-running fixpoint is interruptible rather than only checked at statement boundaries.
Operational Limits (via LocyConfig)¶
max_iterations: recursion cap per recursive stratum.timeout: overall evaluation budget. When set, it also replaces the databasequery_timeoutfor the program's operators, whether above or below it. It covers the whole program: the evaluations it runs again after a write, ASSUME bodies and ABDUCE candidates share what remains of it, and every command runs within it.max_derived_bytes: derived fact memory bound.max_explain_depth: derivation tree depth bound.max_slg_depth: deprecated, no effect (QUERY reads the fixpoint's facts); setting it warns, and it will be removed.goal_directed:Auto(default) answers aQUERYwhose WHERE pins a node KEY column by deriving only what it reaches, and derives a rule only such goals needed on the first read of.derived, against the evaluation's snapshot, so.derivedis unchanged (programs that write,EXPLAIN RULEand transactions are evaluated in full);Offderives every rule in full;Ondoes the rewrite and leaves rules only such goals needed out of.derived;Shadowdoes the rewrite but evaluates every rule. From Python, pass the lowercase string"auto"/"off"/"on"/"shadow".returned_rules:All(default) returns every rule's facts in.derived;Nothingreturns none;Only(names)returns the named rules. Each returned fact is converted to a row and its node and edge ids replaced by the full entities, so a program that derives many facts and reads few of them back is faster with fewer returned. Commands (QUERY,DERIVE, ...) are answered the same, andstats.derived_nodesstill counts every fact. From Python, pass"all","none"or a list of rule names.max_abduce_candidates/max_abduce_results: abduction search bounds.deterministic_best_by: enforce deterministic tie-breaking inBEST BYclauses.strict_probability_domain: reject probability inputs outside[0, 1]instead of clamping.probability_epsilon: MPROD threshold for switching to log-space accumulation.exact_probability: enable BDD-based exact evaluation for shared-proof aggregate groups.max_bdd_variables: cap per-group BDD complexity before fallback.top_k_proofs: keep at mostkrecorded derivations per derived fact forEXPLAIN RULE, the heaviest first (0 keeps all). A derivation's weight, itsproof_probability, is its own PROB value: its local weight times every probability it referenced.
Warning Codes¶
Locy has two warning channels. Runtime warnings (RuntimeWarningCode) surface in result.warnings at evaluation time. Compile-time warnings (WarningCode) surface in compile_warnings when the program is compiled. Both are informational; the program still runs.
Runtime warnings (result.warnings)¶
SharedProbabilisticDependency: multiple proof paths inside one MNOR/MPROD group reuse shared evidence, and the value was computed as if they did not — exact mode was off, or a group exceededmax_bdd_variablesand fell back. The result may overestimate.RuntimeWarning::probabilitycarries the structured diagnostic:inference_mode(approximate,exact,top_k_proofs),resolution(not_attempted,fallback), thereason, the groups detected and fallen back, and the configured and effective variable limits.SharedDependencyResolved(informational,RuntimeWarningCode::is_informational): proof paths share evidence, and exact or top-k proof inference evaluated every shared group without the independence assumption (resolution: completed). Reported instead ofSharedProbabilisticDependency, whose overestimation premise does not hold.BddLimitExceeded: exact mode was enabled, but the group exceededmax_bdd_variablesand fell back to independence mode.CrossGroupCorrelationNotExact: shared evidence spans multiple aggregate groups; each group is exact internally, but correlation across groups is still approximate.FuzzyNotProbabilistic:LocyConfig.semiring = MaxMinProbis active and a rule emitsPROB. Fuzzy-truth math is being applied to a column declared as a probability; either pick the right semiring or drop thePROBannotation.TopKPruningCrossedDependency: underTopKProofs(k), pruning dropped a proof that shared a base fact with a kept proof. The kept set is an approximation; increasekfor exactness.ProbabilityReadNotFactor: a clause'sPROBexpression reads the probability of a positiveISreference other than as one product factor (1 - p,p * p). The referenced probability is not multiplied in again, and exact mode treats each such row as one independent event. See Probabilistic Logic.
Compile-time warnings (compile_warnings)¶
SharedNeuralInputArgument: two or more model invocations in the same rule receive the same INPUT variable argument, so their outputs are correlated. DownstreamMNORunder-estimates joint risk. Mark the models@independentto suppress.SharedNeuralFeatureValue: two or more model invocations in the same rule share an equivalent feature value expression — the same correlation concern even when binding variables differ.@independentsuppresses.SharedRetrievalContext: multiplesimilar_to/semantic_matchfeatures in the same rule share the same query embedding. The features are not independent of each other; the rule's joint composition may be biased.UncalibratedNeuralPredicate: a rule invokes a PROB model declaring noCALIBRATION(orCALIBRATION none); the uncalibrated probability compounds miscalibration downstream.UncalibratedLLMLogprobs: an uncalibratedCREATE MODELwhosexervo_aliaslooks like an LLM provider — raw logprobs are not calibrated probabilities.ProbabilityDomainViolation: a probability input fell outside[0, 1](clamped, or rejected understrict_probability_domain).FoldInRecursivePath: a clause has a recursive IS-ref and a FOLD aggregate but no ALONG. The rule rolls up per KEY, composing level by level; useALONGif you meant to accumulate along each path.EceBinningBias:VALIDATE METRICS ecewas requested; equal-width-binned ECE is biased in the small-sample regime. Preferdebiased_ece.
Recommended Profiles¶
Development¶
- Lower iteration and timeout values.
- Keep deterministic tie-break enabled.
Production¶
- Set explicit timeout and memory budgets.
- Monitor command result sizes.
- Restrict unconstrained
QUERYandABDUCEpatterns.
Escalation Playbook¶
- Reduce goal scope.
- Add stronger filters.
- Split large programs by module.
- Profile expensive rule strata.