v0.55.0 — Reasoning Honesty + Cross-Project Reliability

GraQle v0.55.0 — Reasoning Honesty + Cross-Project Reliability

Five CRs roll up into one release. Graph-health surfacing on every reasoning envelope (CR-004), the cross-project WRITE_COLLISION phantom-error fix that affected every Neo4j-backed graq_learn call (CR-008), the unified config resolver promoted to default-ON with 13 internal call sites migrated (CR-002), defensive guards against silent edge-loss regressions (CR-003), and a TOCTOU-safe stdout_path parameter on graq_bash that closes the long-standing cmd > file.log silent-failure ergonomics class (CR-005a). All shipped under the new BAU CR process.

Install

pip install --upgrade "graqle==0.55.0"

Breaking change

GRAQLE_USE_RESOLVER default flipped from OFF to ON (CR-002 PR-002c-2b). The resolver is now the canonical config-loading path; submodule-aware ancestor walk for graqle.yaml works automatically.

Soft revert: set GRAQLE_USE_RESOLVER=0 (or false / no, case-insensitive) to opt OUT and fall through to the legacy GraqleConfig.from_yaml() path. The resolver-compat helper has a try/except resolver→legacy fallback, so this flip is safe even in environments with a misconfigured resolver — worst case is silent fall-through to the prior behaviour.

Highlights

🩺 Reasoning Honesty — CR-004

Every graq_reason / graq_predict / graq_safety_check envelope now carries an explicit graph_health snapshot:

{
  "answer": "...",
  "confidence": 0.92,
  "graph_health": {
    "node_count": 1234, "edge_count": 8901,
    "chunks_unembedded": 0, "percent_stale": 0.0,
    "activation_mode": "semantic",
    "degraded": false, "reason": null,
    "schema_version": "1"
  }
}

When the graph is degraded, the CLI prints a yellow ⚠ degraded reasoning: … banner before the answer. Probe is contractually never-raises (3-deep defence), adds < 5 ms p95 to envelope build (CI fail-gate). Configurable thresholds: graph_health.stale_chunks_threshold (500), graph_health.edge_node_ratio_threshold (0.5), graph_health.zero_edges_is_degraded (true).

🛠️ Cross-Project WRITE_COLLISION Fix — CR-008

Every graq_learn call on a Neo4j-backed session was returning phantom WRITE_COLLISION even though no write was ever attempted. Replaced ambiguous tuple[bool, int] return with SaveGraphResult + SaveStatus enum (OK / NO_GRAPH_FILE / SHRINK_REFUSED / COLLISION / SAVE_FAILED). NO_GRAPH_FILE folds into recorded=True because the in-memory + backend write already happened. Every project using bolt://... in graqle.yaml benefits — no client migration needed.

🔧 Unified Config Resolver — CR-002

load_via_resolver_or_legacy helper introduced; 13 internal --config typer call sites migrated. GraqleConfig.from_yaml deprecation-warning block delegates to is_resolver_enabled() so both entry points stay in lock-step.

🛡️ Defensive Edge-Loss Guards — CR-003

Hardened guards against the silent edge-loss regression that affected installs between v0.46 and v0.53. Graqle.to_json refuses to shrink edge count by > 10% on graphs with > 100 baseline edges. Neo4j schema parity restored. New scripts/bisect_edge_loss.py utility.

📝 graq_bash stdout_path — CR-005a

graq_bash("cmd > file.log") used to produce empty files because the subprocess shell is sandboxed. New optional stdout_path parameter writes the FULL untruncated stdout to disk atomically. TOCTOU-safe validation (canonicalise → relative_to project_root → defence-in-depth dotdot check). Parent dirs auto-created. Failure isolation — file I/O OSError never masks the subprocess result.

Test count

5,500+ tests across Python 3.10 / 3.11 / 3.12. ~100 new tests this release.

Rollback

Every CR is independently revertable:

CR	Soft revert (no code change)
CR-002	GRAQLE_USE_RESOLVER=0
CR-003	GRAQLE_ALLOW_EDGE_SHRINK=1
CR-004	graph_health.zero_edges_is_degraded: false
CR-005a	Omit stdout_path from graq_bash calls
CR-008	Additive — back-compat shim accepts legacy (bool, int) tuples

What's next

• EU AI Act Wave 1 kicks off immediately following this release — reasoning-honesty foundations from CR-004 will plug directly into Article 13 transparency obligations and Article 12 audit trail requirements.
• Full release notes: CHANGELOG.md § 0.55.0

🤖 Built on the new BAU Change Request process.