[P1] ZARA-015 — Make PrologEngine initialization, queries, and lifecycle fail explicitly #16

New issue

Closed

opened 2026-07-18 19:20:54 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-07-18 19:20:54 +00:00

(Migrated from github.com)

Problem

zara/prolog_engine.py hides important failures:

__init__ ignores a failed consult() and callers can log “ready” with no loaded program.
query_once() collapses logical failure and engine exception into None.
start_timer() and reload_config() return true without checking query success.
query_iter() may leave a query open when iteration errors or the consumer stops early.
User text is interpolated into Prolog source strings with ad-hoc escaping.

Required fix

Raise a typed startup exception when the main program cannot be consulted.
Return/raise distinguishable typed outcomes for success, no solution, and engine error.
Close all query resources in finally paths.
Bind/serialize user data safely instead of constructing executable Prolog source where possible.
Document thread-affinity/serialization requirements for PySWIP and enforce them.

Required tests

Invalid/missing Prolog file, syntax error, no-solution query, runtime exception, generator early close, quoted/backslash/newline input, and concurrent-call policy.
Add scripts/test-prolog-engine.sh with temporary minimal Prolog modules.

Acceptance

Callers cannot mistake engine failure for a valid no-result path.
Startup never reports ready after failed consult.
No leaked query remains after partial iteration.
User text cannot alter the intended goal structure.

Branch

fix/zara-015-prolog-engine-contract

Dependencies

ZARA-003, ZARA-004, ZARA-012.

## Problem `zara/prolog_engine.py` hides important failures: - `__init__` ignores a failed `consult()` and callers can log “ready” with no loaded program. - `query_once()` collapses logical failure and engine exception into `None`. - `start_timer()` and `reload_config()` return true without checking query success. - `query_iter()` may leave a query open when iteration errors or the consumer stops early. - User text is interpolated into Prolog source strings with ad-hoc escaping. ## Required fix - Raise a typed startup exception when the main program cannot be consulted. - Return/raise distinguishable typed outcomes for success, no solution, and engine error. - Close all query resources in `finally` paths. - Bind/serialize user data safely instead of constructing executable Prolog source where possible. - Document thread-affinity/serialization requirements for PySWIP and enforce them. ## Required tests - Invalid/missing Prolog file, syntax error, no-solution query, runtime exception, generator early close, quoted/backslash/newline input, and concurrent-call policy. - Add `scripts/test-prolog-engine.sh` with temporary minimal Prolog modules. ## Acceptance - Callers cannot mistake engine failure for a valid no-result path. - Startup never reports ready after failed consult. - No leaked query remains after partial iteration. - User text cannot alter the intended goal structure. ## Branch `fix/zara-015-prolog-engine-contract` ## Dependencies ZARA-003, ZARA-004, ZARA-012.